Osprey

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

import osprey.server as osprey

# Configure the model + tracker, then start the server (its own process).
osprey.configure(gie_config="/models/gie.txt", tracker="NvSORT")
osprey.serve()                                   # returns once the server is healthy
osprey.add_stream("rtsp://camera/stream", stream_id="cam1")

# Write your analytics with the client — no GStreamer/pyds knowledge needed.
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

One file: configure → serve runs the DeepStream inference pipeline + REST control plane in a separate process, while your DeepStreamClient runs the analytics and serves annotated RTSP. Prefer the CLI (osprey-server / osprey-client) for a production two-service deployment — see below.

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 installs the full DeepStream 8.0 stack bare-metal — so a fresh Ubuntu 24.04 box becomes a working Osprey host.

Target platform (DeepStream 8.0, x86/dGPU):

Quick start (end-to-end)

# 1. Install the Python package (pure-Python + precompiled parser .so)
pip install ospreyai

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

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

# 3b. …or a single Python file (see the example at the top)
python3 my_app.py   # configure() → serve() → your DeepStreamClient

Configuration is either programmatic (osprey.configure(...), shown above) or via environment variables (GIE_0_CONFIG, DS_TRACKER, DS_MODEL_WIDTH …) for the osprey-server CLI. See examples/ for a runnable single-file app.

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.

Python environment — gi + pyds must share the interpreter

Osprey needs three pieces in the same Python interpreter:

Because gi and pyds are not PyPI packages and live in system Python, a plain virtualenv can't see them — that's the usual cause of ModuleNotFoundError: No module named 'gi' (or 'pyds'). Use one of:

# A) No venv (simplest) — install next to system gi/pyds
pip install --break-system-packages ospreyai

# B) A venv that can see system packages (any path)
python3 -m venv --system-site-packages ~/osprey-venv
source ~/osprey-venv/bin/activate
pip install ospreyai

A plain python3 -m venv (without --system-site-packages) will not work — it hides system gi/pyds. The venv's Python must also be the same minor version as system Python (3.12 on Ubuntu 24.04).

Verify any interpreter with:

osprey-doctor      # checks gi + pyds + osprey + plugins, prints the fix if not

Already have DeepStream 8.0?

Skip the bootstrap and just use the library:

pip install ospreyai
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.