Smart Surveillance Demo

This repository provides a smart video surveillance demo for a single-GPU workstation running Ubuntu 24.04 x86_64 and is designed around two local-first demo paths:

• deepstream/: DeepStream 8.0-based local analytics demo
• qwen_vqa/: Qwen-based local Video VQA web demo

Core goals:

• Run near-real-time analysis on local MP4 inputs.
• Produce outputs that are ready to show in a live demo.
• Keep language features optional and isolated, not bundled into local multi-GPU deployments.

Project Overview

The project has three conceptual layers:

1. DeepStream local analytics path
2. Qwen Video VQA local Q&A path
3. optional VSS integration path

                    +-----------------------------------+
                    |        assets/videos/*.mp4        |
                    | crash_cctv_footage.mp4, outputs   |
                    +----------------+------------------+
                                     |
                 +-------------------+-------------------+
                 |                                       |
                 v                                       v
     +---------------------------+          +---------------------------+
     | DeepStream Local Demo     |          | Qwen Video VQA           |
     | deepstream-app in Docker  |          | FastAPI on host          |
     | NVIDIA GPU inference      |          | Frame sampling + VLM     |
     +------------+--------------+          +-------------+------------+
                  |                                           |
                  v                                           v
   +-------------------------------+         +--------------------------------+
   | out_source0_annotated.mp4     |         | Browser UI + Q&A responses     |
   | detection/tracking overlays   |         | timestamps + evidence frames   |
   +-------------------------------+         +--------------------------------+

                                     |
                                     v
                    +-----------------------------------+
                    | Optional Remote VSS Sidecar       |
                    | remote API / summary / reports    |
                    +-----------------------------------+

1. DeepStream Local Analytics

• Runs with Docker and the NVIDIA Container Toolkit.
• Uses assets/videos/crash_cctv_footage.mp4 by default.
• deepstream-app performs inference and overlay rendering.
• Output is written to assets/videos/out_source0_annotated.mp4 by default.

2. Qwen Video VQA

• Single FastAPI service.
• Reads the same sample video, extracts frames, selects relevant frames, and sends them to the VLM.
• Default model is Qwen/Qwen2.5-VL-3B-Instruct.
• Open in a browser at http://localhost:8000.

Descriptive query	Event-detection query

3. Optional VSS Path

• The VSS path is optional.
• It is separate from local DeepStream and is not a hard dependency.
• Provides environment variables and helper containers for remote API / remote VLM / remote LLM connectivity.

Quick Start

1. Environment bootstrap

make bootstrap-env

This creates the following files only if they do not already exist.

• .env
• deepstream/configs/vss/.env
• qwen_vqa/vqa.env

2. Host pre-check

make doctor
make vqa-check

Required prerequisites:

• Ubuntu 24.04 x86_64
• NVIDIA driver and nvidia-smi
• Docker Engine
• Docker Compose v2
• NVIDIA Container Toolkit
• uv (when running qwen_vqa)

3. Download sample video

make download-sample-video

Default input file:

• assets/videos/crash_cctv_footage.mp4

Run The Demos

Run DeepStream demo

Validate composition:

make deepstream-check

Run:

make demo-local

Stop:

make demo-stop

Key outputs:

• Input: assets/videos/crash_cctv_footage.mp4
• Output: assets/videos/out_source0_annotated.mp4

Run Qwen Video VQA

Environment check:

make vqa-check

Run:

make vqa-run

Access URL:

• http://localhost:8000

This path runs directly on the host; the first run may perform uv sync and model download.

Run optional VSS helper

make deepstream-vss-optional

Set remote endpoint and credentials in deepstream/configs/vss/.env before running.

Useful Make Targets

make help
make bootstrap-env
make doctor
make download-sample-video
make deepstream-check
make deepstream-run
make deepstream-stop
make demo-local
make demo-stop
make deepstream-vss-optional
make vqa-check
make vqa-run
make validate

Repository Layout

.
|-- README.md
|-- Makefile
|-- assets/
|-- deepstream/
|   |-- configs/
|   |-- docker/
|   |-- docs/
|   |-- run_demo_local.sh
|   |-- run_vss_optional.sh
|   `-- stop_demo_local.sh
|-- qwen_vqa/
|   |-- app/
|   |-- README.md
|   |-- TROUBLESHOOTING.md
|   |-- check_vqa_env.sh
|   |-- pyproject.toml
|   `-- run_local_vqa.sh
`-- scripts/
    |-- bootstrap_env.sh
    |-- doctor.sh
    `-- validate_repo.sh

Key Paths

• deepstream/docker/compose.deepstream.yml: DeepStream compose for local execution
• deepstream/configs/deepstream/: DeepStream app, analytics, and tracker configuration
• deepstream/docs/: DeepStream execution and operations documentation
• qwen_vqa/app/: FastAPI service and static frontend assets
• scripts/doctor.sh: root environment check
• scripts/validate_repo.sh: repository structure and Compose validation

Documentation Map

• deepstream/docs/getting-started.md: DeepStream getting started guide
• deepstream/docs/architecture.md: Architecture overview
• deepstream/docs/demo-script.md: Demo walkthrough script
• deepstream/docs/troubleshooting.md: Troubleshooting guide
• deepstream/docs/vss-optional.md: Optional VSS integration documentation
• qwen_vqa/README.md: Video VQA detailed documentation
• qwen_vqa/TROUBLESHOOTING.md: VQA path troubleshooting

Current Status

The current state of the repository is as follows:

• The DeepStream local path is configured for single MP4 input-based demos.
• Analysis results are written directly to an annotated MP4 file ready for presentation.
• The Qwen-based Video VQA path is available as a separate component for Q&A over the same sample video.
• The VSS path is isolated as an optional component and does not require a heavy local deployment.

Notes

• This repository prioritizes demo reproducibility and explainability over production-grade systems.
• RTSP, custom model training, and large local multimodal model deployments are out of scope for v1.
• The simplest flow from a fresh clone is: make bootstrap-env → make doctor → make download-sample-video → make demo-local.