Configuration

Configuration Overview

RTSP Human Capture uses a two-tier configuration system:

config.cfg file - INI-style configuration with default values
CLI arguments - Runtime overrides for individual values

CLI arguments always take precedence over config file values. This allows you to use a base configuration and adjust specific parameters per run.

Configuration File (config.cfg)

Default Configuration

The default config.cfg file contains all available settings:

[paths]
# Directory that contains the model files:
#   yolov4.weights, yolov4.cfg  (or yolov3.weights / yolov3.cfg)
#   coco.names
model_dir = model

# Root directory where captured images / video clips are saved.
# For multi-stream runs a sub-folder per stream is created automatically:
#   <output_dir>/stream_<id>/
output_dir = output

[detection]
# Minimum score for a detection to be kept (0.0 – 1.0)
confidence_threshold = 0.5

# Minimum bounding-box area in pixels; smaller detections are discarded
person_area_threshold = 1000

# Analyse every Nth frame  (e.g. 15 ≈ 2 fps on a 30 fps stream)
frame_skip = 15

Configuration Sections

[paths] - File Paths

Controls where the application reads model files and writes output.

Parameter	Type	Default	Description
`model_dir`	string	`model`	Directory containing YOLO weights, config, and coco.names
`output_dir`	string	`output`	Root directory for saved snapshots and video clips

Example:

[paths]
model_dir = /opt/models/yolo
output_dir = /mnt/recordings

[detection] - Detection Parameters

Controls person detection sensitivity and performance.

Parameter	Type	Default	Range	Description
`confidence_threshold`	float	`0.5`	0.0 - 1.0	Minimum detection confidence score
`person_area_threshold`	int	`1000`	0+	Minimum bounding box area in pixels
`frame_skip`	int	`15`	1+	Process every Nth frame

Example:

[detection]
confidence_threshold = 0.65
person_area_threshold = 2000
frame_skip = 10

Configuration Parameters in Detail

model_dir

string

default:"model"

Directory containing YOLO model files. Can be absolute or relative path.

Valid values:

Relative path: model, models/yolo, ./weights
Absolute path: /opt/models, /home/user/yolo

What it should contain:

model/
├── yolov4.weights
├── yolov4.cfg
└── coco.names

Usage in code (person_detector.py:44-45):

self.net = cv2.dnn.readNet(
    f"{model_dir}/yolov4.weights", f"{model_dir}/yolov4.cfg")

output_dir

string

default:"output"

Root directory where captured images and video clips are saved.

Behavior:

Single stream: Files saved directly in output_dir/
Multiple streams: Sub-folders created as output_dir/stream_<id>/

Example structure:

output/
├── stream_1/
│   ├── person_entry_1_20260309_143022_1741528222.jpg
│   └── person_clip_1_20260309_143022_1741528222.mp4
└── stream_2/
    ├── person_entry_1_20260309_143155_1741528315.jpg
    └── person_entry_2_20260309_143420_1741528460.jpg

Auto-creation (stream_processor.py:56-58):

if save_mode is not None:
    person_dir = f"{self.output_dir}/stream_{stream_id}"
    os.makedirs(person_dir, exist_ok=True)

confidence_threshold

float

default:"0.5"

required

Minimum detection confidence score (0.0 to 1.0). Detections below this threshold are discarded.

How it works: Each detection has a confidence score. Only detections exceeding this threshold are kept. Recommendations:

Low (0.3-0.4)

Use when:

Distant cameras
Low light conditions
Prefer false positives over missed detections

Trade-off: More false alarms

Medium (0.5-0.6)

Use when:

Standard conditions
Balanced accuracy needed
General purpose monitoring

Trade-off: Good balance

High (0.7-0.9)

Use when:

High confidence required
Minimize false positives
Clear, well-lit scenes

Trade-off: May miss some detections

Implementation (person_detector.py:131):

if class_id == 0 and confidence > self.confidence_threshold:

Validation (config.py:60-63):

if not 0.0 < confidence_threshold < 1.0:
    raise ValueError(
        f"confidence_threshold must be between 0 and 1, got {confidence_threshold}"
    )

person_area_threshold

integer

default:"1000"

Minimum bounding box area in pixels. Detections with smaller areas are filtered out.

Purpose: Filter out:

Distant/small detections
Partial detections at frame edges
Noise and false positives

Calculation:

area = width * height  # in pixels

Example values:

Threshold	Description	Use Case
500	Very small	Detect distant persons
1000	Small (default)	General purpose
2000	Medium	Close-up monitoring
5000	Large	Only nearby persons

Reference frame sizes:

1920×1080 (Full HD) = 2,073,600 pixels
1280×720 (HD) = 921,600 pixels
640×480 (SD) = 307,200 pixels

Implementation (person_detector.py:147):

if w > 0 and h > 0 and w * h > self.person_area_threshold:

For 1080p streams, person_area_threshold = 1000 means detections must be at least ~32×32 pixels (about 1.5% of frame height).

frame_skip

integer

default:"15"

Process every Nth frame. Higher values improve performance but reduce detection frequency.

Purpose: Balance between:

Performance: Processing every frame is CPU/GPU intensive
Responsiveness: Skipping too many frames delays detection

Effective detection rate:

detection_fps = stream_fps / frame_skip

Examples:

Stream FPS	frame_skip	Detection Rate	Use Case
30	5	6 fps	High responsiveness
30	15	2 fps	Balanced (default)
30	30	1 fps	Low resource usage
25	25	1 fps	Minimal processing

Implementation (stream_processor.py:113):

if frame_count % frame_skip == 0 and (current_time - last_detection_time) >= 0.5:
    last_detection_time = current_time
    has_person, person_count, boxes = self.detector.detect_persons(frame)

Additional throttling: Detection runs at most once per 0.5 seconds, even if frame_skip triggers more frequently.

Recommendations:

High Performance Needed
Balanced (Default)
High Responsiveness

frame_skip = 30  # 1 fps on 30fps stream

Use when:

Running many streams
CPU/GPU limited
Slow detection acceptable

frame_skip = 15  # 2 fps on 30fps stream

Use when:

Standard monitoring
Moderate hardware
Good responsiveness needed

frame_skip = 5  # 6 fps on 30fps stream

Use when:

Fast-moving subjects
Powerful hardware
Quick detection critical

CLI Override Options

All configuration values can be overridden at runtime using command-line arguments.

Configuration File Selection

python main.py --config /path/to/custom.cfg --rtsp "rtsp://..." --save image

string

default:"config.cfg"

Path to configuration file to load.

Detection Parameter Overrides

python main.py --rtsp "rtsp://camera.local/stream" --save image \
  --confidence 0.7

python main.py --rtsp "rtsp://camera.local/stream" --save image \
  --area-threshold 2000

python main.py --rtsp "rtsp://camera.local/stream" --save video \
  --frame-skip 10

python main.py --rtsp "rtsp://camera.local/stream" --save video \
  --confidence 0.65 \
  --area-threshold 1500 \
  --frame-skip 20

Override Implementation

From main.py:89-94:

if args.confidence is not None:
    cfg.confidence_threshold = args.confidence
if args.area_threshold is not None:
    cfg.person_area_threshold = args.area_threshold
if args.frame_skip is not None:
    cfg.frame_skip = args.frame_skip

Overrides only apply when explicitly provided. If a flag is omitted, the config file value is used.

Complete CLI Reference

Flag	Type	Description
`--config PATH`	string	Config file to load (default: `config.cfg`)
`--confidence FLOAT`	float	Confidence threshold (0.0-1.0)
`--area-threshold INT`	int	Minimum person area in pixels
`--frame-skip INT`	int	Process every Nth frame
`--rtsp URL`	string	Single RTSP stream URL
`--rtsp-list URL [URL ...]`	list	Multiple RTSP URLs
`--rtsp-file PATH`	string	File with URLs (one per line)
`--test-image PATH`	string	Test with image file
`--save {image,video}`	choice	Required. Save mode
`--display`	flag	Enable grid display (multi-stream)
`--no-display`	flag	Disable display (single-stream)

Configuration Examples

High Security Monitoring

Scenario: Bank entrance, minimize false alarms

[paths]
model_dir = model
output_dir = /mnt/security/footage

[detection]
confidence_threshold = 0.75  # High confidence required
person_area_threshold = 3000  # Only detect close persons
frame_skip = 10               # Check more frequently

Performance-Optimized Multi-Stream

Scenario: 16 camera warehouse monitoring

[paths]
model_dir = model
output_dir = output

[detection]
confidence_threshold = 0.5    # Standard confidence
person_area_threshold = 1500  # Filter small detections
frame_skip = 30               # Minimize CPU usage

Parking Lot Monitoring

Scenario: Wide-angle distant detection

[paths]
model_dir = model
output_dir = parking_events

[detection]
confidence_threshold = 0.4    # Lower for distant detection
person_area_threshold = 500   # Detect small/distant persons
frame_skip = 20               # Moderate frequency

Configuration Loading

The configuration loading process (from config.py:30-77):

Check file exists

if not os.path.exists(path):
    raise FileNotFoundError(
        f"Config file not found: '{path}'. "
        f"Create one or copy the default config.cfg."
    )

Parse INI file

parser = configparser.ConfigParser()
parser.read(path)

Load values with fallbacks

model_dir = parser.get("paths", "model_dir", fallback="model").strip()
confidence_threshold = parser.getfloat(
    "detection", "confidence_threshold", fallback=0.5
)

Validate values

if not 0.0 < confidence_threshold < 1.0:
    raise ValueError(f"confidence_threshold must be between 0 and 1")
if person_area_threshold < 0:
    raise ValueError(f"person_area_threshold must be >= 0")
if frame_skip < 1:
    raise ValueError(f"frame_skip must be >= 1")

Return AppConfig object

return AppConfig(
    model_dir=model_dir,
    output_dir=output_dir,
    confidence_threshold=confidence_threshold,
    person_area_threshold=person_area_threshold,
    frame_skip=frame_skip,
)

Troubleshooting

Config file not found

Error:

Error: Config file not found: 'config.cfg'. Create one or copy the default config.cfg.

Solution: Create a config.cfg file in your working directory or specify a custom path:

python main.py --config /path/to/config.cfg --rtsp "..." --save image

Invalid confidence threshold

Error:

Config error: confidence_threshold must be between 0 and 1, got 1.5

Solution: Ensure confidence_threshold is between 0.0 and 1.0:

[detection]
confidence_threshold = 0.5  # Must be 0.0 < value < 1.0

Invalid frame_skip value

Error:

Config error: frame_skip must be >= 1, got 0

Solution: Set frame_skip to 1 or higher:

[detection]
frame_skip = 15  # Must be >= 1

CLI overrides not working

Issue: Config file values are used instead of CLI arguments.Check:

Ensure flag syntax is correct: --confidence 0.7 (not --confidence=0.7)
CLI args must come after positional arguments
Use = for some shells: --confidence=0.7

Debug: Look for this output:

Config loaded from: config.cfg
  model_dir   = model
  output_dir  = output

The values shown reflect the final configuration after CLI overrides.

Best Practices

Use Config Files for Defaults

Keep common settings in config.cfg and override specific values via CLI when needed.

Create Environment-Specific Configs

config.dev.cfg
config.production.cfg
config.testing.cfg

Version Control Your Configs

Commit config files (except those with secrets) to track configuration changes over time.

Document Custom Values

Add comments in config files explaining why non-default values were chosen.

Next Steps

Single Stream Processing

Learn to process a single RTSP stream

Multi-Stream Processing

Monitor multiple cameras simultaneously

GPU Acceleration

Speed up detection with CUDA

Model Setup

Configure YOLO models

Get Started

Guides

Examples

Configuration Overview

Configuration File (config.cfg)

Default Configuration

Configuration Sections

Configuration Parameters in Detail

model_dir

output_dir

confidence_threshold

Low (0.3-0.4)

Medium (0.5-0.6)

High (0.7-0.9)

person_area_threshold

frame_skip

CLI Override Options

Configuration File Selection

Detection Parameter Overrides

Override Implementation

Complete CLI Reference

Configuration Examples

High Security Monitoring

Performance-Optimized Multi-Stream

Parking Lot Monitoring

Configuration Loading

Troubleshooting

Best Practices

Use Config Files for Defaults

Create Environment-Specific Configs

Version Control Your Configs

Document Custom Values

Next Steps

Single Stream Processing

Multi-Stream Processing

GPU Acceleration

Model Setup

​Configuration Overview

​Configuration File (config.cfg)

​Default Configuration

​Configuration Sections

​Configuration Parameters in Detail

​model_dir

​output_dir

​confidence_threshold

Low (0.3-0.4)

Medium (0.5-0.6)

High (0.7-0.9)

​person_area_threshold

​frame_skip

​CLI Override Options

​Configuration File Selection

​Detection Parameter Overrides

​Override Implementation

​Complete CLI Reference

​Configuration Examples

​High Security Monitoring

​Performance-Optimized Multi-Stream

​Parking Lot Monitoring

​Configuration Loading

​Troubleshooting

​Best Practices

Use Config Files for Defaults

Create Environment-Specific Configs

Version Control Your Configs

Document Custom Values

​Next Steps

Single Stream Processing

Multi-Stream Processing

GPU Acceleration

Model Setup

Configuration Overview

Configuration File (config.cfg)

Default Configuration

Configuration Sections

Configuration Parameters in Detail

model_dir

output_dir

confidence_threshold

person_area_threshold

frame_skip

CLI Override Options

Configuration File Selection

Detection Parameter Overrides

Override Implementation

Complete CLI Reference

Configuration Examples

High Security Monitoring

Performance-Optimized Multi-Stream

Parking Lot Monitoring

Configuration Loading

Troubleshooting

Best Practices

Next Steps