Metadata-Version: 2.4
Name: matrice_streaming
Version: 0.22.0
Summary: Common server utilities for Matrice.ai services
Author-email: "Matrice.ai" <dipendra@matrice.ai>
License: MIT
Keywords: matrice,streaming,utilities,mypyc,compiled
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE.txt
Provides-Extra: runtime
Requires-Dist: psutil>=7.2.2; extra == "runtime"
Provides-Extra: dev
Requires-Dist: pytest==9.1.1; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.15.1; extra == "dev"
Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.8.0; extra == "dev"
Requires-Dist: packaging>=26.3; extra == "dev"
Requires-Dist: fakeredis>=2.37.0; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"
Requires-Dist: numpy>=2.4.4; extra == "dev"
Requires-Dist: opencv-python-headless>=4.13.0.92; extra == "dev"
Requires-Dist: pyzmq==27.2.0; extra == "dev"
Requires-Dist: msgpack==1.2.3; extra == "dev"
Requires-Dist: redis>=8.1.0; extra == "dev"
Requires-Dist: psutil>=7.2.2; extra == "dev"
Requires-Dist: pydantic>=2.13.5; extra == "dev"
Requires-Dist: ruff==0.16.10; extra == "dev"
Requires-Dist: bandit[toml]==1.9.4; extra == "dev"
Requires-Dist: mypy==2.4.0; extra == "dev"
Requires-Dist: pre-commit==4.6.2; extra == "dev"
Requires-Dist: pip-audit==2.10.1; extra == "dev"
Requires-Dist: coverage[toml]>=7.16.1; extra == "dev"
Requires-Dist: matrice-common<1,>=0.16.0; extra == "dev"
Dynamic: license-file
Dynamic: requires-python

# 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

```bash
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/`](docs/README.md). Start with the
[docs index](docs/README.md), which gives the session reading order and a glossary.
The chapters most readers need first:

| # | Chapter | One line |
|---|---------|----------|
| 01 | [Architecture overview](docs/01-architecture-overview.md) | `StreamingAction` → `StreamingGateway` → one decode backend, the process/thread model, and lifecycle states. |
| 03 | [NVDEC pipeline](docs/03-nvdec-pipeline.md) | The production decode path: demuxers, codec handling, per-GPU worker processes, the decoder pool, and the watchdog. |
| 07 | [Configuration and ops](docs/07-configuration-and-ops.md) | Environment variables and constructor parameters, plus production symptoms → causes → knobs. |
| 15 | [Local dev and testing](docs/15-local-dev-and-testing.md) | Running the gateway and its tests on a development host. |

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

## License

See [LICENSE](LICENSE).
