Osprey

Dynamic, multi-stream video-analytics library built on NVIDIA DeepStream 8.0 — installable with pip, run bare-metal, no Docker.

from osprey.client import DeepStreamClient, FrameData

class VehicleCounter(DeepStreamClient):
    def _process_frame(self, frame: FrameData):
        for obj in frame.objects:
            self._draw_object(frame.surface, obj)   # box + tracking label

VehicleCounter().start()   # serves RTSP for every discovered stream

What Osprey installs for you

Osprey is a Python layer on top of the DeepStream SDK. The GStreamer plugins (nvstreammux, nvinfer, nvtracker, nvunixfdsink/src, nvdsosd, …) and the pyds bindings are not on PyPI. Rather than make you set that up by hand, Osprey ships an end-to-end bootstrap that reproduces, bare-metal, what the DeepStream container image build does — so a fresh Ubuntu 24.04 box becomes a working Osprey host with no Docker.

Target platform (DeepStream 8.0, x86/dGPU):

Quick start (end-to-end)

# 1. Install the Python package (pure-Python + precompiled parser .so)
pip install "osprey[server]"

# 2. Bootstrap the DeepStream stack bare-metal (needs root; ~one-time)
sudo osprey-bootstrap

# 3. Run
osprey-server     # FastAPI control plane on :8000  (POST /api/v1/add …)
osprey-client     # discovers sockets, serves RTSP per stream

osprey-bootstrap runs five stages (each also runnable on its own; see below). If the NVIDIA driver is (re)installed in stage 10, reboot before running the pipeline.

Bootstrap stages

Useful toggles (read by the scripts, pass straight through):

sudo OSPREY_ASSUME_CUDA=1 osprey-bootstrap    # already have driver/CUDA/TRT/cuDNN
sudo OSPREY_ONLY=30 osprey-bootstrap          # run a single stage (e.g. just pyds)
sudo OSPREY_DS_VERSION=8.0 osprey-bootstrap   # override DeepStream version

Security note. Osprey does not auto-download or overwrite your system TensorRT library. Some ONNX models embed end-to-end NMS (EfficientNMS_TRT) and need a patched libnvinfer_plugin; because that means replacing a system library with an external binary, Osprey leaves it as a deliberate manual step (see the reference patch_libnvinfer.sh). Standard YOLO/RT-DETR detection and segmentation need no patch.

Already have DeepStream 8.0?

Skip the bootstrap and just use the library:

pip install "osprey[server]"
python3 -c "from osprey.client import DeepStreamClient; print('ok')"

The bundled native libraries (osprey/**/lib/*.so) are compiled for DeepStream 8.0 / CUDA 12.8 and match the platform table above.

CLIs

Testing

To exercise the library in a GPU DeepStream container (install → REST add → GPU inference → RTSP output), see docs/TESTING.md. It's the exact runbook used to validate Osprey end-to-end.