matrice_streaming — Streaming Gateway

matrice_streaming is the Streaming Gateway (SG), the frame producer of the Matrice video pipeline. Given a set of cameras, it opens each stream (RTSP fronted by MediaMTX, or file/HTTP sources), decodes frames at a target FPS, and publishes every decoded frame into a per-camera shared-memory ring buffer that downstream processes — primarily the inference engine — attach to and read zero-copy. Cameras are added, updated, and removed at runtime without restarting the process, driven by Kafka events plus a periodic backend poll.

There are two decode backends, chosen at construction:

• NVDEC (GPU) — the production path. Frames stay on the GPU as NV12 surfaces and are handed to the inference engine through CUDA IPC.
• OpenCV (CPU) — a cv2.VideoCapture-based fallback for hosts without a usable GPU decode stack.

SG does not run inference and does not force preprocessing: frames are published at native resolution and the inference engine owns resize/letterbox/color conversion.

Install

pip install matrice_streaming

Heavy runtime dependencies (NVDEC/CuPy, OpenCV, Kafka and Redis clients) are provided by the deployment image rather than declared as hard dependencies of the wheel.

Public API

Everything external lives under matrice_streaming.streaming_gateway:

• StreamingAction — the production entry point; turns an action_id into a running, monitored, auto-restarting gateway.
• StreamingGateway — the orchestrator underneath, used directly in tests or custom control loops.
• InstanceStreamingGatewayUtil / StreamingGatewayUtil — backend API clients.
• InputStream — the per-camera config dataclass.
• InstanceEventListener — Kafka-driven camera reconciliation.

Documentation

The knowledge-transfer docs live in docs/. Start with the docs index, which gives the session reading order and a glossary. The chapters most readers need first:

Contributor workflow (hooks, signed commits, trailers) is in CONTRIBUTING.md and docs/git-hooks-commit-workflow.md.

License

See LICENSE.