deepstream_reference_apps: the sample pipelines behind NVIDIA's video analytics stack

A sample repository whose README already points somewhere else

The first line of the README is a redirect, and it is worth reading before anything else: this repository has ceased updates, and the current DeepStream reference applications live at NVIDIA/deepstream. That statement sits directly above a heading announcing samples for DeepStream 9.0, so the repository is caught between two eras. The metadata adds a third data point. The project is not archived, and the last push was on 2026-07-15, which is recent enough to mean someone still commits here. None of those facts contradict each other outright, so the useful reading is narrower: bug fixes and small corrections may land, while new samples go to the other repository.

There is a second inconsistency worth keeping in view. The README says it currently provides three different reference applications, then goes on to describe ten of them. The repository tree is longer again, with fifteen sample directories. The count in that sentence is stale prose, not a statement about what is actually in the checkout, so use the tree rather than the sentence when you work out what is available.

The repository description is short and to the point: samples for TensorRT and DeepStream for Tesla and Jetson. That is the scope. Nothing here runs on a generic x86 workstation without significant adaptation, because the samples are written against hardware decoders and DeepStream's GStreamer plugin set.

Cloning into the SDK sample_apps directory rather than anywhere else

The Getting Started section gives one instruction, and it is about location rather than flags. The samples are expected to live inside the DeepStream installation at `/opt/nvidia/deepstream/deepstream/sources/apps/sample_apps/`, and the README warns that doing so may require sudo permission. The reason is not spelled out, but it is visible in the sample descriptions: these applications link against DeepStream's own source tree and plugin set, so dropping a sample into an unrelated directory leaves the build without the headers and libraries it expects.

cd /opt/nvidia/deepstream/deepstream/sources/apps/sample_apps/
git clone https://github.com/NVIDIA-AI-IOT/deepstream_reference_apps

Each sample then carries its own README, and the top-level page is effectively an index of those links. After cloning, what you find is a flat set of sample directories:

anomaly/
deepstream-masktracker/
deepstream-tracker-3d-multi-view/
deepstream-vllm-plugin/

The naming is inconsistent in a useful way. Most directories carry a `deepstream-` prefix, while `anomaly/`, `legacy_apps/`, `pyservicemaker_sample_apps/` and `runtime_source_add_delete/` do not. If you are scripting anything against this checkout, match on the directory name rather than assuming the prefix holds.

Anomaly detection through an auxiliary optical flow plugin

The `anomaly/` sample is the smallest of the set and the clearest statement of what a sample here is for. The README describes it as containing an auxiliary dsdirection plugin to show the capability of DeepStream in anomaly detection. The sample image in the repository is named `.opticalflow.png`, which tells you the mechanism is optical flow rather than a frame-by-frame classifier.

This is the shape of everything else in the repository. A sample demonstrates one DeepStream capability by supplying the missing plugin or the awkward configuration, not by shipping an application you would deploy unchanged. Reading `anomaly/` teaches you where a custom GStreamer element slots into the pipeline and how its output is consumed downstream. That knowledge transfers to your own plugin work; the sample itself does not.

`runtime_source_add_delete/` sits next to it in purpose and is arguably more useful for anyone building a live system. It demonstrates adding and deleting video sources in a running DeepStream pipeline, which is the operation that separates a pipeline built once at startup from one that can follow a changing camera list.

MaskTracker, single-view 3D, and fusing calibrated cameras

Three tracking samples form a progression in ambition. `deepstream-masktracker/` demonstrates DeepStream MaskTracker for multi-object tracking and segmentation using SAM2, with a retail output clip as its sample result. Segmentation masks flowing out of a tracking pipeline are what make counting or per-region behaviour analysis possible, so this is the sample to read when your problem is about people inside a region rather than where they are on screen.

`deepstream-tracker-3d/` moves to single-view 3D tracking, reconstructing a 3D human model in world coordinates under occlusion. The phrase to notice is world coordinates. Once positions are expressed in world space rather than pixel space, they can be compared across frames and across views without any hand-rolled calibration arithmetic.

`deepstream-tracker-3d-multi-view/` is where that pays off. The README describes the samples as demonstrating multi-view 3D tracking in a distributed, real-time framework built for large-scale calibrated camera networks. The two included images are a four-camera overlay and a bird's-eye view of the fused result, which is the clearest statement of the payoff: several cameras observing the same scene converge into one top-down picture. The cost is that calibration becomes a hard requirement, and the README does not document how to produce the calibration files.

Tiling, buffer sharing and one decoder for many sources

The middle of the tree is a set of pipeline mechanics rather than end-user demos, and these are the samples most worth reading. `deepstream-custom-tile-config/` demonstrates the custom-tile-config option of `nvmultistreamtiler`, which controls the tiling positions and sizes of multiple videos in a batch. Batch inference needs this when your video streams have different aspect ratios, because the default tiling stretches or crops in ways that quietly degrade detector accuracy.

`deepstream-ipc-test-sr/` shows how to share video buffers over inter-process communication and how to change output video buffers. When two pipelines need the same decoded frames, passing buffers rather than copying pixel data is the difference between a working and an unusable topology.

`deepstream-dynamicsrcbin-test/` covers `nvdsdynamicsrcbin`, which lets many dynamic sources share a single video decoder, aimed at high decoder throughput scenarios. Decoders are the scarce resource on Jetson, so this is a genuinely useful trick.

Two more complete the set. `deepstream_parallel_inference_app/` implements multiple models running inference in parallel through the DeepStream APIs, and `deepstream-bodypose-3d/` customises preprocessing for a multi-input-layer model along with bodypose 3D postprocessing. One directory, `deepstream-3d-sensor-fusion/`, appears in the tree but is described nowhere on the README page, so its contents are not documented at this level.

The vLLM plugin, Python Service Maker and where to go next

`deepstream-vllm-plugin/` is the newest-looking item in the tree and the one with the widest appeal beyond NVIDIA hardware: a GStreamer plugin for DeepStream that integrates vision-language models using vLLM for real-time video understanding and analysis. Its README is a separate link, and the plugin's dependency on vLLM is the practical constraint to check first, since it pulls in a serving stack rather than just a model file.

The Python side sits in `pyservicemaker_sample_apps/`, described as additional samples for the Python API of DeepStream Service Maker, using either the flow API or the pipeline API. The README links the DeepStream Service Maker Python documentation for details, which is the right place for the API surface. This is the practical answer for teams who want the tracking samples' ideas without writing C++.

Finally, `legacy_apps/` holds samples that are no longer supported, moved there for various reasons the README declines to specify. Read it as an archive, not as options.

For a reader arriving cold, the sensible order is: the Service Maker Python docs first if you want to avoid C++, then the multi-view tracking sample if you have calibrated cameras, then the vLLM plugin if you want a language model in the loop. The current versions of all of these are at the NVIDIA/deepstream repository the README names.

Editorial conclusion

Treat this repository as a working reference rather than a dependency. It is genuinely good for reading how DeepStream wires batching, tiling, IPC and inference parallelism together, and the per-sample directories still carry individual READMEs with build details that no top-level page repeats. It is the wrong place to start a new project, because the README's first line sends you to the NVIDIA/deepstream repository for current work, and the version here is pinned to DeepStream 9.0. If you are on 9.0 and need multi-view tracking or the vLLM plugin specifically, clone it into the sample_apps directory of your SDK install and read that sample's own README before touching a config file. If you are on any other SDK version, go to the repository the README names and verify the sample list there against your installed `deepstream-app` version.

Frequently asked questions

Official sources

1. Issues
2. NVIDIA-AI-IOT/deepstream_reference_apps on GitHub
3. README