shot-detection 0.1.0

Standalone Python shot boundary detection package for splitting videos into shots

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. If you want to make video shots searchable and enable more professional video understanding workflows, visit 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

pip install shot-detection

Import from shot_detection:

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

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

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

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.