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.
