deepstream-app Config Generator
Purpose
Generate validated deepstream-app and deepstream-test5-app configuration
files from a bounded requirements spec, with explicit output-path safeguards.
When to Use This Skill
Use this skill when a user needs a new deepstream-app or
deepstream-test5-app config, wants a generated config repaired through its
source spec, or asks for creation-time tuning of sources, streammux, inference,
tracking, display, latency, RTSP, or message-broker settings.
Prerequisites
- DeepStream SDK 9.2.x with
deepstream-appordeepstream-test5-apponPATH. - Python 3.10+ and the PyYAML version pinned in
scripts/requirements.txt. - A user-writable directory for the spec and generated output.
Verify parser keys before targeting another DeepStream release.
Inputs
Accept one of: --quickstart, a YAML/JSON spec path, detailed prose that can be
mapped to a spec, or answers to the interactive questions. For non-quickstart
generation, source kind/location and intended sink are required; profile,
platform, inference, and tracker settings are optional.
When values conflict, use this precedence: supplied spec file, explicit user arguments, unambiguous agent context, then documented defaults. This skill has no persistent state file. Never infer credentials or retain secrets in a spec.
When NOT to use
- User supplies a pre-existing config and asks to audit or sanity-check it →
use deepstream-audit-config. The bundled
scripts/validate.pyis only the render-time linter for this skill's own generation/repair workflow. - User already has a working config and only wants to run or debug it → do not re-render or claim an independent audit.
- User asks to fix an NVBugs ticket, profile with Nsight, or write custom GStreamer/C code → other skills.
- User names an invalid
profile(anything other thanlatency,perf,display,custom) → reject and list valid values. Ask for at most 1 profile clarification; if the response is still invalid or absent, abort without rendering. Never pass an invalid value through torender.py.
Instructions
- Select the operating mode from the inputs and workflow below.
- Write
--outonly to a user-writable path such as./generated_config.txtor./quickstart_generated.txt; generated configs use absolute paths internally. - Mention the root-owned stock samples directory under
/opt/nvidia/deepstream/...only when the user explicitly asks, and never run privileged commands on the user's behalf. - On
PermissionError, make at most 1 writable-path retry with an explicit alternate--outafter surfacingrender.py's recovery message. If that retry fails, abort generation and report the error.
Workflow
- [ ] Step 1: Detect mode (A quickstart / B spec / C prose / D Q&A)
- [ ] Step 2: Gather requirements
- [ ] Step 3: Profile overlay (automatic in render.py)
- [ ] Step 4: Render via scripts/render.py
- [ ] Step 5: Validate via scripts/validate.py
- [ ] Step 6: Print deepstream-app -c <path>
When the host provides a run_script helper, invoke the bundled scripts rather
than reproducing their logic. Equivalent calls are:
run_script("scripts/render.py", ["--spec", spec_path, "--out", output_path])
run_script("scripts/validate.py", [output_path])
Otherwise, use the python3 commands shown below.
Default: Mode D (interactive Q&A). Do not ask "which mode?" — infer from the invocation:
| Signal | Mode |
|---|---|
| "quickstart", "starter", "just run", "I'm new" | A — skip Q&A |
--spec, pasted YAML, spec file path |
B — skip Q&A |
| Detailed prose with ≥3 inferable fields | C — build spec, confirm assumptions |
| Anything else | D — references/interactive_qa.md |
Mode A — Quickstart
python3 scripts/render.py --quickstart --out ./quickstart_generated.txt
python3 scripts/validate.py ./quickstart_generated.txt
deepstream-app -c ./quickstart_generated.txt
Bundled spec: assets/templates/quickstart_spec.yaml. Worked examples: references/examples.md.
Mode B — Spec file
User supplied a spec → Step 4.
Mode C — Natural language
Build YAML per scripts/spec_schema.yaml and references/natural_language_mapping.md. List assumptions before rendering.
Mode D — Interactive Q&A
Follow references/interactive_qa.md. First question must include the quickstart escape hatch.
Step 3: Profile overlay
Automatic in render.py. Explain choices from references/profiles.md.
Step 4: Render
python3 scripts/render.py --spec <spec.yaml> --out <writable-output-path>
Step 5: Validate
python3 scripts/validate.py <output_path>
On validation errors, make at most 1 targeted correction to the spec, re-render, and validate 1 more time. If validation still fails, abort further corrections and report the remaining errors; do not loop or hand-edit generated configs.
Step 6: Run command
deepstream-app -c <output_path> # deployment.app == classic
deepstream-test5-app -c <output_path> # deployment.app == test5
Relative paths inside the config resolve relative to the config file's directory.
Output Format
Return the generated .txt, .yml, or .yaml config path, any explicitly
requested inference/tracker sidecar paths, the validation result, and the exact
deepstream-app -c or deepstream-test5-app -c command. Do not claim success
unless validation passes. Before writing to an already-present output path,
show its path and obtain explicit confirmation; commands are proposals for
review, not permission to execute them.
Examples
# Starter config
python3 scripts/render.py --quickstart --out ./generated_config.txt
python3 scripts/validate.py ./generated_config.txt
# Spec → config
python3 scripts/render.py --spec ./my_spec.yaml --out ./generated_config.txt
python3 scripts/validate.py ./generated_config.txt
More worked examples: references/examples.md.
Available Scripts
| Script | Purpose | Arguments |
|---|---|---|
scripts/render.py |
Spec → config | --spec <yaml>, --quickstart, --out <path>, --print-resolved-spec |
scripts/render_infer.py |
Render a standalone nvinfer detector/classifier config; also imported by render.py |
--network-type, --batch-size, model paths, --out <path> |
scripts/render_tracker.py |
Render a standalone NvDCF/NvSORT/IOU tracker YAML; also imported by render.py |
--algorithm, supported tracker overrides, --out <path> |
scripts/validate.py |
Config linter | <config-path>, --help |
--print-resolved-spec still writes the config and, after a successful
render, emits the normalized/default-resolved spec to standard error.
Limitations
- Parser keys and templates are validated for DeepStream 9.2.x only.
validate.pychecks generated structure; it cannot prove that models, cameras, brokers, drivers, or plugins will work at runtime.- This workflow does not independently audit arbitrary pre-existing configs.
Troubleshooting
| Error | Cause | Resolution |
|---|---|---|
PyYAML import failure |
Pinned dependency is absent | Install scripts/requirements.txt in the active environment. |
SyntaxError: f-string expression part cannot include a backslash |
An older skill revision used Python 3.12-only f-string syntax | Update to the compatibility-fixed skill revision; if updating is not possible, use Python 3.12+ for that older revision. |
| Permission denied | Output directory is not writable | Retry once with an explicit user-writable --out; then stop. |
| Invalid profile | Value is outside the four supported profiles | Ask once for latency, perf, display, or custom. |
| Validation failure | The spec rendered an inconsistent config | Correct the spec once, re-render and revalidate; report remaining errors. |
Guardrails
profilemust belatency,perf,display, orcustomonly. Reject unknown values before render;render.pyexits 2 on invalid profiles.- Always render through
scripts/render.py— never hand-write configs in chat. - Use scripts/spec_schema.yaml for accepted spec fields and references/reference.md for authoritative DeepStream config keys; do not invent keys.
- Never skip
validate.py. - Do not auto-promote
msgbrokerto test5 unless the user wantsmessage-consumer. - Default
--out ./generated_config.txt; no privileged commands.
Additional resources
- Spec schema: scripts/spec_schema.yaml
- Quickstart spec: assets/templates/quickstart_spec.yaml
- Config key reference: references/reference.md
- Profile deltas: references/profiles.md
- Worked examples: references/examples.md
- Validator pitfalls: references/validator_pitfalls.md