shot-detection 0.1.0__tar.gz

shot_detection-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,54 @@
+name: Publish PyPI
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/shot-detection/
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v5
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

shot_detection-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: shot-detection
+Version: 0.1.0
+Summary: Standalone Python shot boundary detection package for splitting videos into shots
+Project-URL: Homepage, https://github.com/Seeknetic/shot-detection-python
+Project-URL: Repository, https://github.com/Seeknetic/shot-detection-python
+Author: Seeknetic
+License-Expression: Apache-2.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: onnxruntime<2,>=1.17
+Requires-Dist: typing-extensions<5,>=4.9
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Shot Detection Python
+
+Standalone Python package for shot boundary detection.
+
+It takes a video file, runs TransNetV2-style ONNX inference on low-resolution RGB frames, and returns shot ranges with millisecond timestamps.
+
+Built by [Seeknetic](https://www.seeknetic.com/). If you want to make video shots searchable and enable more professional video understanding workflows, visit [seeknetic.com](https://www.seeknetic.com/).
+
+## What it does
+
+- Probes the input video with `ffprobe`
+- Extracts low-resolution frames with `ffmpeg`
+- Runs sliding-window ONNX inference
+- Finds shot boundaries
+- Converts them into `{start_ms, end_ms}` shot segments
+
+## Installation
+
+```bash
+pip install shot-detection
+```
+
+Import from `shot_detection`:
+
+```python
+from shot_detection import ShotDetector
+```
+
+You also need:
+
+- `ffmpeg`
+- `ffprobe`
+
+On first run, the package downloads the default model automatically:
+
+- URL: `https://download.shotai.io/model/shot-detection/transnetv2_open_fp16.onnx`
+- cache dir:
+  - Linux/macOS: `~/.cache/shot-detection/models/`
+  - Windows: `%LOCALAPPDATA%\\shot-detection\\models\\`
+
+You can override the cache root with `SHOT_DETECTION_CACHE_DIR`.
+
+## Usage
+
+```python
+from shot_detection import ShotDetector
+
+detector = ShotDetector()
+shots = detector.detect("/path/to/video.mp4")
+
+for shot in shots:
+    print(shot.start_ms, shot.end_ms)
+```
+
+## Advanced usage
+
+```python
+from shot_detection import detect_shots
+
+shots = detect_shots(
+    video_path="/path/to/video.mp4",
+    threshold=0.5,
+    min_shot_duration_ms=500,
+)
+```
+
+## Custom model path
+
+```python
+from shot_detection import ShotDetector
+
+detector = ShotDetector(model_path="/path/to/custom-transnetv2.onnx")
+```
+
+## Notes
+
+- The package expects the ONNX model input to accept 100-frame windows at `48x27` RGB.
+- `ffmpeg` decode is adaptive: it prefers system-native hardware decoding when available and falls back to software decoding automatically.
+- CUDA is intentionally not part of the default decode plan.

shot_detection-0.1.0/README.md

@@ -0,0 +1,79 @@
+# Shot Detection Python
+
+Standalone Python package for shot boundary detection.
+
+It takes a video file, runs TransNetV2-style ONNX inference on low-resolution RGB frames, and returns shot ranges with millisecond timestamps.
+
+Built by [Seeknetic](https://www.seeknetic.com/). If you want to make video shots searchable and enable more professional video understanding workflows, visit [seeknetic.com](https://www.seeknetic.com/).
+
+## What it does
+
+- Probes the input video with `ffprobe`
+- Extracts low-resolution frames with `ffmpeg`
+- Runs sliding-window ONNX inference
+- Finds shot boundaries
+- Converts them into `{start_ms, end_ms}` shot segments
+
+## Installation
+
+```bash
+pip install shot-detection
+```
+
+Import from `shot_detection`:
+
+```python
+from shot_detection import ShotDetector
+```
+
+You also need:
+
+- `ffmpeg`
+- `ffprobe`
+
+On first run, the package downloads the default model automatically:
+
+- URL: `https://download.shotai.io/model/shot-detection/transnetv2_open_fp16.onnx`
+- cache dir:
+  - Linux/macOS: `~/.cache/shot-detection/models/`
+  - Windows: `%LOCALAPPDATA%\\shot-detection\\models\\`
+
+You can override the cache root with `SHOT_DETECTION_CACHE_DIR`.
+
+## Usage
+
+```python
+from shot_detection import ShotDetector
+
+detector = ShotDetector()
+shots = detector.detect("/path/to/video.mp4")
+
+for shot in shots:
+    print(shot.start_ms, shot.end_ms)
+```
+
+## Advanced usage
+
+```python
+from shot_detection import detect_shots
+
+shots = detect_shots(
+    video_path="/path/to/video.mp4",
+    threshold=0.5,
+    min_shot_duration_ms=500,
+)
+```
+
+## Custom model path
+
+```python
+from shot_detection import ShotDetector
+
+detector = ShotDetector(model_path="/path/to/custom-transnetv2.onnx")
+```
+
+## Notes
+
+- The package expects the ONNX model input to accept 100-frame windows at `48x27` RGB.
+- `ffmpeg` decode is adaptive: it prefers system-native hardware decoding when available and falls back to software decoding automatically.
+- CUDA is intentionally not part of the default decode plan.

shot_detection-0.1.0/bin/publish-pypi

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+
+set -eux
+rm -rf dist
+mkdir -p dist
+uv build
+if [ -n "${PYPI_TOKEN:-}" ]; then
+  uv publish --token="$PYPI_TOKEN"
+else
+  uv publish
+fi

shot_detection-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "shot-detection"
+version = "0.1.0"
+description = "Standalone Python shot boundary detection package for splitting videos into shots"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+  { name = "Seeknetic" },
+]
+requires-python = ">=3.9"
+dependencies = [
+  "numpy>=1.24,<3",
+  "onnxruntime>=1.17,<2",
+  "typing-extensions>=4.9,<5",
+]
+classifiers = [
+  "Typing :: Typed",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Operating System :: OS Independent",
+  "License :: OSI Approved :: Apache Software License",
+  "Topic :: Multimedia :: Video",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://github.com/Seeknetic/shot-detection-python"
+Repository = "https://github.com/Seeknetic/shot-detection-python"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8,<9",
+]
+
+[build-system]
+requires = ["hatchling>=1.26,<2"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shot_detection"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

shot_detection-0.1.0/src/shot_detection/__init__.py

@@ -0,0 +1,24 @@
+from .detector import ShotDetector, detect_shots, detect_shots_detailed
+from .errors import ShotDetectionError
+from .model_manager import (
+    DEFAULT_MODEL_URL,
+    ensure_default_model,
+    get_default_cache_dir,
+    get_default_model_path,
+)
+from .types import DetectionResult, ShotBoundary, ShotSegment, VideoMetadata
+
+__all__ = [
+    "ShotDetector",
+    "ShotDetectionError",
+    "DEFAULT_MODEL_URL",
+    "ShotBoundary",
+    "ShotSegment",
+    "VideoMetadata",
+    "DetectionResult",
+    "ensure_default_model",
+    "get_default_cache_dir",
+    "get_default_model_path",
+    "detect_shots",
+    "detect_shots_detailed",
+]

shot_detection-0.1.0/src/shot_detection/detector.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import math
+from pathlib import Path
+
+import numpy as np
+
+from .errors import ShotDetectionError
+from .ffmpeg import MODEL_INPUT_HEIGHT, MODEL_INPUT_WIDTH, extract_low_res_rgb_frames, probe_video
+from .inference import MODEL_INPUT_CHANNELS, WINDOW_SIZE, TransNetV2ONNX
+from .model_manager import ensure_default_model
+from .types import DetectionResult, ShotBoundary, ShotSegment
+
+WINDOW_STEP = WINDOW_SIZE - 10
+DEFAULT_THRESHOLD = 0.5
+DEFAULT_MIN_SHOT_DURATION_MS = 500
+
+
+class ShotDetector:
+    def __init__(
+        self,
+        *,
+        model_path: str | Path | None = None,
+        threshold: float = DEFAULT_THRESHOLD,
+        min_shot_duration_ms: int = DEFAULT_MIN_SHOT_DURATION_MS,
+        model_cache_dir: str | Path | None = None,
+    ) -> None:
+        resolved_model_path = ensure_default_model(model_path=model_path, cache_dir=model_cache_dir)
+        self.model = TransNetV2ONNX(resolved_model_path)
+        self.threshold = threshold
+        self.min_shot_duration_ms = min_shot_duration_ms
+
+    def detect(self, video_path: str | Path) -> list[ShotSegment]:
+        return self.detect_detailed(video_path).shots
+
+    def detect_detailed(self, video_path: str | Path) -> DetectionResult:
+        metadata = probe_video(video_path)
+        raw_frames = extract_low_res_rgb_frames(video_path)
+        frame_size = MODEL_INPUT_WIDTH * MODEL_INPUT_HEIGHT * MODEL_INPUT_CHANNELS
+        total_frames = len(raw_frames) // frame_size
+
+        if total_frames <= 0:
+            raise ShotDetectionError("No frames were extracted from the input video")
+
+        frames = np.frombuffer(raw_frames[: total_frames * frame_size], dtype=np.uint8).reshape(
+            total_frames,
+            MODEL_INPUT_HEIGHT,
+            MODEL_INPUT_WIDTH,
+            MODEL_INPUT_CHANNELS,
+        )
+
+        all_probs: list[float] = []
+
+        for start in range(0, total_frames, WINDOW_STEP):
+            end = min(start + WINDOW_SIZE, total_frames)
+            window_frames = end - start
+            if window_frames < 10:
+                break
+
+            buffer = np.zeros(
+                (1, WINDOW_SIZE, MODEL_INPUT_HEIGHT, MODEL_INPUT_WIDTH, MODEL_INPUT_CHANNELS),
+                dtype=np.uint8,
+            )
+            buffer[0, :window_frames] = frames[start:end]
+
+            probs = self.model.infer(buffer)
+            for offset in range(window_frames):
+                frame_index = start + offset
+                if frame_index >= len(all_probs):
+                    all_probs.append(_to_boundary_probability(float(probs[offset])))
+
+        peak_indices = find_peaks(np.asarray(all_probs, dtype=np.float32), self.threshold)
+        boundaries = [
+            ShotBoundary(
+                frame_index=frame_index,
+                timestamp_ms=int(round((frame_index / metadata.fps) * 1000)),
+                confidence=float(all_probs[frame_index]),
+            )
+            for frame_index in peak_indices
+        ]
+        shots = boundaries_to_shots(boundaries, metadata.duration_ms, self.min_shot_duration_ms)
+
+        return DetectionResult(
+            boundaries=boundaries,
+            shots=shots,
+            total_frames=total_frames,
+            fps=metadata.fps,
+            duration_ms=metadata.duration_ms,
+        )
+
+
+def detect_shots(
+    *,
+    video_path: str | Path,
+    model_path: str | Path | None = None,
+    threshold: float = DEFAULT_THRESHOLD,
+    min_shot_duration_ms: int = DEFAULT_MIN_SHOT_DURATION_MS,
+    model_cache_dir: str | Path | None = None,
+) -> list[ShotSegment]:
+    detector = ShotDetector(
+        model_path=model_path,
+        threshold=threshold,
+        min_shot_duration_ms=min_shot_duration_ms,
+        model_cache_dir=model_cache_dir,
+    )
+    return detector.detect(video_path)
+
+
+def detect_shots_detailed(
+    *,
+    video_path: str | Path,
+    model_path: str | Path | None = None,
+    threshold: float = DEFAULT_THRESHOLD,
+    min_shot_duration_ms: int = DEFAULT_MIN_SHOT_DURATION_MS,
+    model_cache_dir: str | Path | None = None,
+) -> DetectionResult:
+    detector = ShotDetector(
+        model_path=model_path,
+        threshold=threshold,
+        min_shot_duration_ms=min_shot_duration_ms,
+        model_cache_dir=model_cache_dir,
+    )
+    return detector.detect_detailed(video_path)
+
+
+def _to_boundary_probability(value: float) -> float:
+    if 0.0 <= value <= 1.0:
+        return value
+    return 1.0 / (1.0 + math.exp(-value))
+
+
+def find_peaks(probs: np.ndarray, threshold: float, min_distance: int = 10) -> list[int]:
+    peaks: list[int] = []
+
+    for index in range(1, len(probs) - 1):
+        current = float(probs[index])
+        previous = float(probs[index - 1])
+        following = float(probs[index + 1])
+
+        if current > threshold and current > previous and current > following:
+            if not peaks or index - peaks[-1] >= min_distance:
+                peaks.append(index)
+            elif current > float(probs[peaks[-1]]):
+                peaks[-1] = index
+
+    return peaks
+
+
+def boundaries_to_shots(
+    boundaries: list[ShotBoundary],
+    duration_ms: int,
+    min_shot_duration_ms: int = DEFAULT_MIN_SHOT_DURATION_MS,
+) -> list[ShotSegment]:
+    start_points = [0, *[boundary.timestamp_ms for boundary in boundaries]]
+    end_points = [*[boundary.timestamp_ms for boundary in boundaries], duration_ms]
+
+    shots = [
+        ShotSegment(index=index, start_ms=start_points[index], end_ms=end_points[index])
+        for index in range(len(start_points))
+    ]
+    return merge_short_shots(shots, min_shot_duration_ms)
+
+
+def merge_short_shots(shots: list[ShotSegment], min_shot_duration_ms: int) -> list[ShotSegment]:
+    if len(shots) <= 1:
+        return shots
+
+    merged = [
+        {"index": shot.index, "start_ms": shot.start_ms, "end_ms": shot.end_ms}
+        for shot in shots
+    ]
+
+    has_short = True
+    while has_short:
+        has_short = False
+        next_shots: list[dict[str, int]] = []
+
+        for index, shot in enumerate(merged):
+            duration = shot["end_ms"] - shot["start_ms"]
+            if duration >= min_shot_duration_ms:
+                next_shots.append(shot)
+                continue
+
+            has_short = True
+            previous = next_shots[-1] if next_shots else None
+            following = merged[index + 1] if index + 1 < len(merged) else None
+
+            if previous is None and following is not None:
+                following["start_ms"] = shot["start_ms"]
+            elif previous is not None and following is None:
+                previous["end_ms"] = shot["end_ms"]
+            elif previous is not None and following is not None:
+                previous_duration = previous["end_ms"] - previous["start_ms"]
+                following_duration = following["end_ms"] - following["start_ms"]
+                if previous_duration <= following_duration:
+                    previous["end_ms"] = shot["end_ms"]
+                else:
+                    following["start_ms"] = shot["start_ms"]
+
+        merged = next_shots
+        if len(merged) <= 1:
+            break
+
+    return [
+        ShotSegment(index=index, start_ms=shot["start_ms"], end_ms=shot["end_ms"])
+        for index, shot in enumerate(merged)
+    ]

shot_detection-0.1.0/src/shot_detection/errors.py

@@ -0,0 +1,2 @@
+class ShotDetectionError(RuntimeError):
+    """Raised when shot detection preprocessing or inference fails."""

shot_detection-0.1.0/src/shot_detection/ffmpeg.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import ShotDetectionError
+from .types import VideoMetadata
+
+MODEL_INPUT_WIDTH = 48
+MODEL_INPUT_HEIGHT = 27
+
+
+@dataclass(frozen=True)
+class FfmpegRuntimeCapabilities:
+    hwaccels: set[str]
+    decoders: set[str]
+
+
+@dataclass(frozen=True)
+class FfmpegInputPlan:
+    label: str
+    input_options: list[str]
+    uses_hardware_decode: bool
+
+
+def resolve_binary(name: str) -> str:
+    binary = shutil.which(name)
+    if binary is None:
+        raise ShotDetectionError(
+            f"Required binary '{name}' was not found on PATH. Please install FFmpeg before running shot detection."
+        )
+    return binary
+
+
+def run_command(command: list[str]) -> subprocess.CompletedProcess[bytes]:
+    try:
+        return subprocess.run(command, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    except subprocess.CalledProcessError as exc:
+        message = exc.stderr.decode("utf-8", errors="replace").strip() or str(exc)
+        raise ShotDetectionError(message) from exc
+
+
+def _parse_ffmpeg_list(output: str) -> set[str]:
+    values: set[str] = set()
+    for line in output.splitlines():
+        trimmed = line.strip()
+        if not trimmed:
+            continue
+
+        parts = trimmed.split()
+        if len(parts) >= 2 and parts[0].isupper():
+            values.add(parts[1].lower())
+        elif trimmed.isidentifier():
+            values.add(trimmed.lower())
+
+    return values
+
+
+def get_runtime_capabilities(ffmpeg_path: str) -> FfmpegRuntimeCapabilities:
+    hwaccels = _parse_ffmpeg_list(run_command([ffmpeg_path, "-hide_banner", "-hwaccels"]).stdout.decode("utf-8"))
+    decoders = _parse_ffmpeg_list(run_command([ffmpeg_path, "-hide_banner", "-decoders"]).stdout.decode("utf-8"))
+    return FfmpegRuntimeCapabilities(hwaccels=hwaccels, decoders=decoders)
+
+
+def _linux_vaapi_options() -> list[str] | None:
+    dri_dir = Path("/dev/dri")
+    if not dri_dir.exists():
+        return None
+
+    render_nodes = sorted(dri_dir.glob("renderD*"))
+    if not render_nodes:
+        return None
+
+    return [
+        "-threads",
+        "1",
+        "-hwaccel",
+        "vaapi",
+        "-hwaccel_output_format",
+        "vaapi",
+        "-vaapi_device",
+        str(render_nodes[0]),
+    ]
+
+
+def get_decode_plans(platform_name: str | None = None) -> list[FfmpegInputPlan]:
+    ffmpeg_path = resolve_binary("ffmpeg")
+    capabilities = get_runtime_capabilities(ffmpeg_path)
+    platform_name = platform_name or sys.platform
+
+    plans: list[FfmpegInputPlan] = []
+
+    if platform_name == "darwin" and "videotoolbox" in capabilities.hwaccels:
+        plans.append(
+            FfmpegInputPlan(
+                label="videotoolbox-hardware",
+                input_options=["-threads", "1", "-hwaccel", "videotoolbox"],
+                uses_hardware_decode=True,
+            )
+        )
+
+    if platform_name == "win32":
+        if "d3d12va" in capabilities.hwaccels:
+            plans.append(
+                FfmpegInputPlan(
+                    label="d3d12va-hardware",
+                    input_options=["-threads", "1", "-hwaccel", "d3d12va", "-hwaccel_output_format", "d3d12"],
+                    uses_hardware_decode=True,
+                )
+            )
+        if "d3d11va" in capabilities.hwaccels:
+            plans.append(
+                FfmpegInputPlan(
+                    label="d3d11va-hardware",
+                    input_options=["-threads", "1", "-hwaccel", "d3d11va", "-hwaccel_output_format", "d3d11"],
+                    uses_hardware_decode=True,
+                )
+            )
+        if "dxva2" in capabilities.hwaccels:
+            plans.append(
+                FfmpegInputPlan(
+                    label="dxva2-hardware",
+                    input_options=["-threads", "1", "-hwaccel", "dxva2", "-hwaccel_output_format", "dxva2_vld"],
+                    uses_hardware_decode=True,
+                )
+            )
+
+    if platform_name.startswith("linux") and "vaapi" in capabilities.hwaccels:
+        vaapi_options = _linux_vaapi_options()
+        if vaapi_options is not None:
+            plans.append(
+                FfmpegInputPlan(
+                    label="vaapi-hardware",
+                    input_options=vaapi_options,
+                    uses_hardware_decode=True,
+                )
+            )
+
+    plans.append(
+        FfmpegInputPlan(
+            label="software-fallback",
+            input_options=["-threads", "1"],
+            uses_hardware_decode=False,
+        )
+    )
+    return plans
+
+
+def _requires_hwdownload(plan: FfmpegInputPlan, platform_name: str | None = None) -> bool:
+    platform_name = platform_name or sys.platform
+    if platform_name == "darwin" and plan.label == "videotoolbox-hardware":
+        return False
+    return plan.uses_hardware_decode
+
+
+def probe_video(video_path: str | Path) -> VideoMetadata:
+    ffprobe_path = resolve_binary("ffprobe")
+    result = run_command(
+        [
+            ffprobe_path,
+            "-v",
+            "error",
+            "-show_streams",
+            "-show_format",
+            "-print_format",
+            "json",
+            str(video_path),
+        ]
+    )
+
+    try:
+        payload = json.loads(result.stdout.decode("utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ShotDetectionError("Failed to parse ffprobe output") from exc
+
+    streams = payload.get("streams")
+    if not isinstance(streams, list):
+        raise ShotDetectionError("ffprobe did not return stream metadata")
+
+    video_stream = next((stream for stream in streams if stream.get("codec_type") == "video"), None)
+    if not isinstance(video_stream, dict):
+        raise ShotDetectionError("No video stream found in the input file")
+
+    width = int(video_stream.get("width") or 0)
+    height = int(video_stream.get("height") or 0)
+    fps = _parse_frame_rate(video_stream.get("avg_frame_rate") or video_stream.get("r_frame_rate"))
+    duration_seconds = _parse_duration_seconds(payload.get("format"), video_stream)
+
+    if width <= 0 or height <= 0 or fps <= 0 or duration_seconds <= 0:
+        raise ShotDetectionError("Unable to determine valid video metadata")
+
+    return VideoMetadata(
+        duration_ms=int(round(duration_seconds * 1000)),
+        width=width,
+        height=height,
+        fps=fps,
+        codec=video_stream.get("codec_name"),
+    )
+
+
+def _parse_frame_rate(value: object) -> float:
+    if not isinstance(value, str) or not value:
+        return 0.0
+
+    if "/" in value:
+        numerator_text, denominator_text = value.split("/", 1)
+        try:
+            numerator = float(numerator_text)
+            denominator = float(denominator_text)
+        except ValueError:
+            return 0.0
+        return 0.0 if denominator == 0 else numerator / denominator
+
+    try:
+        return float(value)
+    except ValueError:
+        return 0.0
+
+
+def _parse_duration_seconds(format_info: object, video_stream: dict[str, object]) -> float:
+    if isinstance(format_info, dict):
+        try:
+            duration = float(format_info.get("duration") or 0.0)
+        except (TypeError, ValueError):
+            duration = 0.0
+        if duration > 0:
+            return duration
+
+    try:
+        return float(video_stream.get("duration") or 0.0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def extract_low_res_rgb_frames(
+    video_path: str | Path,
+    *,
+    width: int = MODEL_INPUT_WIDTH,
+    height: int = MODEL_INPUT_HEIGHT,
+) -> bytes:
+    ffmpeg_path = resolve_binary("ffmpeg")
+    last_error: ShotDetectionError | None = None
+
+    for plan in get_decode_plans():
+        scale_filter = f"scale={width}:{height}:flags=fast_bilinear"
+        if _requires_hwdownload(plan):
+            filter_chain = f"hwdownload,format=nv12,{scale_filter},format=rgb24"
+        else:
+            filter_chain = f"{scale_filter},format=rgb24"
+
+        command = [
+            ffmpeg_path,
+            "-v",
+            "error",
+            *plan.input_options,
+            "-i",
+            str(video_path),
+            "-vf",
+            filter_chain,
+            "-pix_fmt",
+            "rgb24",
+            "-vsync",
+            "0",
+            "-f",
+            "rawvideo",
+            "pipe:1",
+        ]
+
+        try:
+            return run_command(command).stdout
+        except ShotDetectionError as exc:
+            last_error = exc
+
+    if last_error is not None:
+        raise last_error
+
+    raise ShotDetectionError("No FFmpeg decode plan was available")

shot_detection-0.1.0/src/shot_detection/inference.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import onnxruntime as ort
+
+from .errors import ShotDetectionError
+
+WINDOW_SIZE = 100
+MODEL_INPUT_WIDTH = 48
+MODEL_INPUT_HEIGHT = 27
+MODEL_INPUT_CHANNELS = 3
+MODEL_INPUT_SIZE = WINDOW_SIZE * MODEL_INPUT_WIDTH * MODEL_INPUT_HEIGHT * MODEL_INPUT_CHANNELS
+
+
+class TransNetV2ONNX:
+    def __init__(self, model_path: str | Path) -> None:
+        self.model_path = str(model_path)
+        self._session = self._create_session(self.model_path)
+        self._input_name = self._session.get_inputs()[0].name
+        self._output_name = self._session.get_outputs()[0].name
+        self._input_type = self._session.get_inputs()[0].type
+
+    def _create_session(self, model_path: str) -> ort.InferenceSession:
+        path = Path(model_path)
+        if not path.is_file():
+            raise ShotDetectionError(f"Model file not found: {model_path}")
+
+        available_providers = ort.get_available_providers()
+        preferred_order = [
+            "CoreMLExecutionProvider",
+            "DmlExecutionProvider",
+            "CPUExecutionProvider",
+        ]
+        providers = [provider for provider in preferred_order if provider in available_providers]
+        if not providers:
+            providers = available_providers
+        if not providers:
+            raise ShotDetectionError("No ONNX Runtime execution provider is available")
+
+        try:
+            return ort.InferenceSession(model_path, providers=providers)
+        except Exception as exc:  # pragma: no cover
+            raise ShotDetectionError(f"Failed to initialize ONNX Runtime session: {exc}") from exc
+
+    def infer(self, frames: np.ndarray) -> np.ndarray:
+        if frames.shape != (1, WINDOW_SIZE, MODEL_INPUT_HEIGHT, MODEL_INPUT_WIDTH, MODEL_INPUT_CHANNELS):
+            raise ShotDetectionError(f"Unexpected frame tensor shape: {frames.shape}")
+
+        if self._input_type == "tensor(uint8)":
+            input_data = frames.astype(np.uint8, copy=False)
+        else:
+            input_data = frames.astype(np.float32, copy=False)
+
+        try:
+            outputs = self._session.run([self._output_name], {self._input_name: input_data})
+        except Exception as exc:  # pragma: no cover
+            raise ShotDetectionError(f"ONNX inference failed: {exc}") from exc
+
+        output = np.asarray(outputs[0]).reshape(-1)
+        if output.size < WINDOW_SIZE:
+            raise ShotDetectionError(f"Model output is too short: {output.size}")
+
+        return output[:WINDOW_SIZE]

shot_detection-0.1.0/src/shot_detection/model_manager.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+import tempfile
+import urllib.request
+from pathlib import Path
+
+from .errors import ShotDetectionError
+
+DEFAULT_MODEL_URL = "https://download.shotai.io/model/shot-detection/transnetv2_open_fp16.onnx"
+DEFAULT_MODEL_FILENAME = "transnetv2_open_fp16.onnx"
+DEFAULT_CACHE_DIRNAME = "shot-detection"
+
+
+def get_default_cache_dir() -> Path:
+    override = os.environ.get("SHOT_DETECTION_CACHE_DIR")
+    if override:
+        return Path(override).expanduser()
+
+    if os.name == "nt":
+        local_app_data = os.environ.get("LOCALAPPDATA")
+        if local_app_data:
+            return Path(local_app_data) / DEFAULT_CACHE_DIRNAME
+
+    xdg_cache_home = os.environ.get("XDG_CACHE_HOME")
+    if xdg_cache_home:
+        return Path(xdg_cache_home) / DEFAULT_CACHE_DIRNAME
+
+    return Path.home() / ".cache" / DEFAULT_CACHE_DIRNAME
+
+
+def get_default_model_path(cache_dir: str | Path | None = None) -> Path:
+    base_dir = Path(cache_dir).expanduser() if cache_dir is not None else get_default_cache_dir()
+    return base_dir / "models" / DEFAULT_MODEL_FILENAME
+
+
+def ensure_default_model(
+    *,
+    model_path: str | Path | None = None,
+    cache_dir: str | Path | None = None,
+    model_url: str = DEFAULT_MODEL_URL,
+    timeout_seconds: int = 60,
+) -> Path:
+    resolved_path = Path(model_path).expanduser() if model_path is not None else get_default_model_path(cache_dir)
+    if resolved_path.is_file():
+        return resolved_path
+
+    resolved_path.parent.mkdir(parents=True, exist_ok=True)
+    temp_file_handle = tempfile.NamedTemporaryFile(
+        prefix=resolved_path.stem + ".",
+        suffix=".tmp",
+        dir=resolved_path.parent,
+        delete=False,
+    )
+    temp_path = Path(temp_file_handle.name)
+    temp_file_handle.close()
+
+    try:
+        with urllib.request.urlopen(model_url, timeout=timeout_seconds) as response, temp_path.open("wb") as file_obj:
+            while True:
+                chunk = response.read(1024 * 1024)
+                if not chunk:
+                    break
+                file_obj.write(chunk)
+
+        if temp_path.stat().st_size == 0:
+            raise ShotDetectionError(f"Downloaded model is empty: {model_url}")
+
+        os.replace(temp_path, resolved_path)
+        return resolved_path
+    except Exception as exc:
+        temp_path.unlink(missing_ok=True)
+        raise ShotDetectionError(
+            f"Failed to download the default shot detection model from {model_url}: {exc}"
+        ) from exc

shot_detection-0.1.0/src/shot_detection/py.typed

@@ -0,0 +1 @@
+

shot_detection-0.1.0/src/shot_detection/types.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class VideoMetadata:
+    duration_ms: int
+    width: int
+    height: int
+    fps: float
+    codec: str | None = None
+
+
+@dataclass(frozen=True)
+class ShotBoundary:
+    frame_index: int
+    timestamp_ms: int
+    confidence: float
+
+
+@dataclass(frozen=True)
+class ShotSegment:
+    index: int
+    start_ms: int
+    end_ms: int
+
+
+@dataclass(frozen=True)
+class DetectionResult:
+    boundaries: list[ShotBoundary]
+    shots: list[ShotSegment]
+    total_frames: int
+    fps: float
+    duration_ms: int

shot_detection-0.1.0/tests/test_detector.py

@@ -0,0 +1,33 @@
+from shot_detection.detector import boundaries_to_shots, find_peaks, merge_short_shots
+from shot_detection.types import ShotBoundary, ShotSegment
+
+
+def test_find_peaks_prefers_stronger_peak_when_too_close() -> None:
+    peaks = find_peaks(__import__("numpy").array([0.0, 0.7, 0.0, 0.8, 0.0], dtype="float32"), 0.5, min_distance=10)
+    assert peaks == [3]
+
+
+def test_boundaries_to_shots_returns_ranges_in_ms() -> None:
+    boundaries = [
+        ShotBoundary(frame_index=10, timestamp_ms=1000, confidence=0.9),
+        ShotBoundary(frame_index=20, timestamp_ms=2500, confidence=0.8),
+    ]
+    shots = boundaries_to_shots(boundaries, duration_ms=4000, min_shot_duration_ms=100)
+    assert shots == [
+        ShotSegment(index=0, start_ms=0, end_ms=1000),
+        ShotSegment(index=1, start_ms=1000, end_ms=2500),
+        ShotSegment(index=2, start_ms=2500, end_ms=4000),
+    ]
+
+
+def test_merge_short_shots_merges_short_middle_segment() -> None:
+    shots = [
+        ShotSegment(index=0, start_ms=0, end_ms=1000),
+        ShotSegment(index=1, start_ms=1000, end_ms=1200),
+        ShotSegment(index=2, start_ms=1200, end_ms=3000),
+    ]
+    merged = merge_short_shots(shots, min_shot_duration_ms=500)
+    assert merged == [
+        ShotSegment(index=0, start_ms=0, end_ms=1200),
+        ShotSegment(index=1, start_ms=1200, end_ms=3000),
+    ]

shot_detection-0.1.0/tests/test_model_manager.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+from shot_detection.model_manager import ensure_default_model, get_default_model_path
+
+
+class _FakeResponse:
+    def __init__(self, payload: bytes) -> None:
+        self._buffer = io.BytesIO(payload)
+
+    def read(self, size: int = -1) -> bytes:
+        return self._buffer.read(size)
+
+    def __enter__(self) -> "_FakeResponse":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        return None
+
+
+def test_get_default_model_path_uses_cache_dir(tmp_path: Path) -> None:
+    model_path = get_default_model_path(tmp_path)
+    assert model_path == tmp_path / "models" / "transnetv2_open_fp16.onnx"
+
+
+def test_ensure_default_model_downloads_once(monkeypatch, tmp_path: Path) -> None:
+    payload = b"fake-onnx-model"
+    calls: list[str] = []
+
+    def fake_urlopen(url: str, timeout: int = 60) -> _FakeResponse:
+        calls.append(url)
+        return _FakeResponse(payload)
+
+    monkeypatch.setattr("shot_detection.model_manager.urllib.request.urlopen", fake_urlopen)
+
+    model_path = ensure_default_model(cache_dir=tmp_path)
+    assert model_path.is_file()
+    assert model_path.read_bytes() == payload
+    assert len(calls) == 1
+
+    same_path = ensure_default_model(cache_dir=tmp_path)
+    assert same_path == model_path
+    assert len(calls) == 1