Configuration

The first time you start PeopleTracker, a people-config.ini is created in the directory you have specified. Please note that anytime you change the contents of people-config.ini, you will need to restart the Docker container .

people-config.ini
# List of TZ names on https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
timezone = UTC

[cameras]

  # Image file name, you can use any format codes
  # from https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes
  image_format = $(camera)_screenshots/%y-%m-%d/%H-%M-%S.%f.jpg

  [[camera-1]]
    active = yes
    url = rtsp://your-camera.com:8554/demo
    webhook-target = webhook-1
    sample = 5

    # Save to CSV file. The corresponding frame is stored as an image in the same directory.
    # See more formats on https://guides.platerecognizer.com/docs/other-apps/people-tracker/configuration#output-formats
    csv_file = $(camera)_%y-%m-%d.csv

[webhooks]

  [[webhook-1]]
    url = http://my-webhook-1.site
    image = yes

Hierarchical Configuration

people-config.ini file defines parameters that will be used by all cameras or just one.

When parameters are defined at the [cameras] level, they apply to all cameras. When they are defined at the [[camera-id]] level, they apply to a single camera.

people-config.ini
[cameras]
  # Parameters for all cameras
  sample = 5
  image_format = $(camera)_screenshots/%y-%m-%d/%H-%M-%S.%f.jpg
  csv_file = $(camera)_%y-%m-%d.csv

  [[camera-1]]
    # Parameters set only for camera-1
    active = yes
    url = rtsp://192.168.0.108:8080/video/camera-1
    sample = 3 # sample = 3 is only applied for camera-1

  [[camera-2]]
    # Parameters set only for camera-2
    active = yes
    url = rtsp://192.168.0.108:8080/video/camera-2
    # sample = 5 defined in [cameras]

info

Some parameters are disabled by default, they are marked with the character # at the beginning of the line. To activate the parameter, it is necessary to remove this mark, save the file and restart the Docker container.

Parameters

active

PeopleTracker processes all the cameras defined in the config file if active is set to yes. See example above.

sample

This parameter lets you skip frames in situations where you have limited hardware and/or do not need to process all the frames of the video or camera feed.

By default, sample = 2, so PeopleTracker processes every other frame.
Set sample = 3 if you want to process every third frame.

timezone

You can set the timezone for the timestamp in the CSV and also Webhooks output.
If you omit this field, then the default timezone output will be UTC.
See list of supported time zones.
Plate Recognizer automatically adjusts for time changes (e.g. daylight savings, standard time) for each timezone. Examples: a) For Silicon Valley, use timezone = America/Los_Angeles b) For Budapest, use timezone = Europe/Budapest. You can also use timezone = Europe/Berlin.

The timestamp field is the time the person was captured by the camera. We are using the operating system clock and we apply the timezone from people-config.ini.

url

To run PeopleTracker on a RTSP camera feed, just specify the URL to point to the RTSP file. For example:

url = rtsp://192.168.0.108:8080/video/h264

url = rtsp://admin:[email protected]:8080/video/h264
# where admin is the username and 12345 is the password

For additional help with RTSP, please go to https://www.getscw.com/decoding/rtsp
You can also process video files.

Output Formats

csv_file

Indicate the filename of the CSV output you’d like to save.
The name can be dynamic. Refer to the field image_format for details. For example:

csv_file = $(camera)_%y-%m-%d.csv

jsonlines_file

Save the prediction results to a JSON file. For example:

jsonlines_file = my_camera_results.jsonl
jsonlines_file = $(camera)_%y-%m-%d.jsonl

We are using the JSON Lines format. Refer to the field image_format for details.

image_format

Save images in a particular folder with a specific filename. In the example above, images are saved in the directory <camera_id>_screenshots (one per camera) with the filename <timestamp>.jpg. Images are saved when csv_file or jsonlines_file is used. If webhooks are used, images may temporarily be saved to disk.

Filename customization:
- If $(camera) is used, it is replaced with the camera's name. For example, camera-1.
- If the current date is 2020-06-03 20:54:35. %y-%m-%d/%H-%M-%S.jpg is replaced by 20-06-03/20-54-35.jpg. Letters starting with the percent sign are converted according to those rules https://strftime.org/
- For example, to put images from all cameras into the same folder: image_format = screenshots/$(camera)_%y-%m-%d_%H-%M-%S.%f.jpg
If you don't need to save images, you can leave it empty: image_format =.

caution

If you have a webhook with images, image_format should NOT be empty.

video_format

Save video clips of detected persons by adding this to your people-config.ini:

video_format = $(camera)_videos/%y-%m-%d/%H-%M-%S.%f.mp4

If you don't need to save videos, you can leave it empty:

video_format =

note

Currently only .mp4 output format is supported. We may add more formats in the future.

important

After a video file has been sent out to a webhook, it gets removed from disk. Otherwise, it is kept forever.

danger

Enabling the feature to save video clips not only substantially increases CPU usage but also consumes significant storage space. Prior to enabling this feature, ensure you have spare processing capacity and sufficient available storage.

video_before

When a video clip is saved, PeopleTracker records a few seconds before the person was detected. This time is controlled by the video_before parameter. The default value is 5 seconds.

video_after

When a video clip is saved, PeopleTracker records a few seconds after the person was detected. This time is controlled by the video_after parameter. The default value is 5 seconds.

note

Total video duration could differ slightly from values specified in video_before and video_after due to encoding and frame rate differences.

video_fps

There are two options for video clips frame rate: video_fps = native (default) records frames at the rate PeopleTracker is reading them from the source; video_fps = sample records frames at the reduced rate specified by the sample parameter.

video_overlay

It is possible to add an information overlay to video clips, to gain insight into the operation of PeopleTracker and simplify troubleshooting or config tuning. This parameter can be set to one or several (separated by comma) of the available options:

all: turns all available overlays on;
boxes: draws bounding boxes for detected persons, each in its own unique color;
trace: draws a person's trajectory;
dscores: adds detection scores on top of the bounding boxes;
confirmed: adds a rolling text box with detection event information in the same color as the person's bounding box; note that it is displayed when PeopleTracker is reporting this information, which is usually after the person has left the frame (see max_dwell_delay), so adjust video_after appropriately;
dwell_time: adds a rolling text box with dwell time information (similar to confirmed, see max_dwell_delay and video_after);
health_score: adds Health Score number to the frame;
timestamp: adds the time in the specified timezone to the frame and to the confirmed overlay, identifying the moment of detection/dwell events;
position_sec: adds an internal video second counter useful for video files, similar to timestamp.

note

PeopleTracker can only add overlays to sample frames, so setting video_fps = sample is recommended when using video_overlay.

video_codec

There are two options for video clips codec: video_codec = mp4v (default) encodes video clips with MPEG-4 Part 2 codec; video_codec = h264 encodes video clips with H.264 codec.

danger

H.264 encoding requires significantly more CPU and memory resources, which may not yield real-time processing and could lead to abrupt crashes. If crashes occur with video_codec = h264, increase your Docker or WSL resource limits, as these crashes are likely due to RAM limitations in Docker or WSL.

Advanced Parameters

dwell_time

PeopleTracker can estimate the time a person spends in the area and then send this information out by a separate webhook. To enable this feature, set dwell_time = true. The time is calculated as the difference in seconds between the first and last moments the person was visible.

New in version 1.5.0.

max_dwell_delay

When a person disappears from view, PeopleTracker waits for max_dwell_delay (15 seconds by default) before sending a webhook with dwelling time information. This is done to ignore temporary obstructions. You can set this parameter to a lower value to receive dwelling time faster at the cost of accuracy.

trajectory

PeopleTracker can report the trajectory of a person along with dwell info. To enable that, set trajectory = true.

New in version 1.5.0.

info

Trajectory needs dwell_time to be enabled.

Webhook Parameters

PeopleTracker can automatically send a notification to an URL, when a tracked object is confirmed as a person within the video stream. You can use Webhooks as well as save images and CSV files in a folder. By default, no Webhooks are sent.

How Webhooks Are Sent

If the target cannot be reached (HTTP errors or timeout), the request is retried 3 times.
If it is still failing, the data is saved to disk. That can be turned off using caching webhook parameter.
- When a webhook fails, all new webhook data will be directly saved to disk.
- Every 2 minutes, there is an attempt to send the cached webhooks. If a send is successful, we will also process the data saved to disk if there is any.
- When webhooks are saved to disk, we remove the oldest data when the free disk space is low.

Format and Fields

Description of the webhook data format.

webhook_targets

To send data to webhooks, you must list them in webhook_targets camera property of the people-config.ini.
The recognition data and image are encoded in multipart/form-data.
To ensure that your webhook_targets endpoint is correct, please test it out at www.webhook.site.

You can send to multiple targets by simply listing all the targets. Each target has its own set of parameters: url, image, header.

webhook_targets = my-webhook-1, my-webhook-2

webhook descriptors

Each webhook you are planning to use should be described in [webhooks] section of the people-config.ini file. This section also uses Hierarchical Configuration structure:

people-config.ini
# Webhook targets and their parameters
[webhooks]
  image = yes

  [[my-webhook-1]]
    url = http://my-webhook-1.site

  [[my-webhook-2]]
    url = http://my-webhook-2.site
    image = no

url (webhook)

Specifies the URL to send the webhook data to. For example:

url = http://my-webhook-1.site

image

This field can be set to either:
```
image = yes
image = no
```
When image = no is set, it will send only the recognition data but the image data will not be sent to the target URL. This lets your system receive the information faster.

image_quality

JPEG quality for webhook images, from 1 to 100 (default 80). The lower the quality the smaller the image size.

New in version 1.5.0.

video

This field can be set to either:
```
video = file
video = url
video = no
```
When video = file is set (default), the video clip with the timestamp and person detection information will be sent to the target URL.
When video = url is set, PeopleTracker will send only the video file information, but the video file itself will not be sent to the target URL. This option is reserved for future use.
When video = no is set, no video information will be sent to the webhook.

note

Video information is sent separately from detection data, when the video file becomes available. See Get Results for webhook JSON format details.

caching

If a webhook fails, it is by default cached to disk and retried later. To turn this off, use caching = no.

request_timeout

A webhook request will timeout after request_timeout seconds. The default value is 30 seconds.

The webhook request can have a custom header. To set it, use header = Name: example. By default no custom header is used.

Starting with version 1.5.0, the header parameter now accepts multiple values. Multiple headers should be separated by a comma. If a header value contains a comma, it must be escaped with a backslash.

For example,

header = "Authorization: Token ************, Accept-Encoding: gzip\, deflate"

Other Parameters

Detection Zone

Detection Zones exclude trees, street signs or other objects. For more info, read our blog on Detection Zones.

To start, go to our Detection Zone in your Plate Rec Account Page and upload a capture from the camera set up on the PeopleTracker.
Add the camera_id parameter, it is between [[]] in your people-config.ini configuration file, make sure they are identical. The image below represents an example whose camera_id is 'camera_1". After these steps click "Add Zone".

people-config.ini
  [cameras]
    # Global cameras parameters here
    [[camera_1]]
      active = yes
      url = rtsp://<rtsp_user>:<rtsp_password>@<rtsp_url>:<rtsp_port>/<rtsp_camera_path>
      # More camera parameters below
      # ...

The system will load the added image and a page similar to the image below will display it, then you can follow the on-screen instructions to draw exclusion areas over the image to determine the zones that will be ignored in the detection. Once you are done, click "Save Zone".
Make sure to restart the Docker container and that machine has internet access at the time of the restart to see the effects. When you open your PeopleTracker folder, you will now see one file per zone.

Editing Zone Files

To edit a detection zone, Click Edit on Detection Zone then follow step (3). After this, remove the file zone_camera-id.png from the PeopleTracker folder then follow step (4). When you open your PeopleTracker folder, you will now see the new file zone_camera-id.png.

Removing Zone Files

To remove a detection zone, click Remove on Detection Zone. Then remove the file zone_camera-id.png from the PeopleTracker folder.

Detection Zone Files

After following the steps above, you will have new files in your PeopleTracker folder. For example, if you create a detection zone for camera1, you will have an image at /path/to/PeopleTracker/zone_camera1.png.

You can also manually create a detection zone mask. Here are the requirements.

Create a PNG image in your PeopleTracker folder. Check the file permissions; it should be readable by your Docker user.
Name the file zone_camera-id.png (replace camera-id with the ID of your camera).
Use only two colors: black for masked areas and white for everything else.
The image resolution should match the resolution used by the camera.

Summary

Use people-config.ini to configure all PeopleTracker settings, including cameras, output formats, and webhooks.
Hierarchical configuration allows global defaults at the [cameras] level and per-camera overrides at the [[camera-id]] level.
Output formats include CSV (csv_file), JSON Lines (jsonlines_file), saved images (image_format), and video clips (video_format).
Video clip options — control recording duration with video_before and video_after, frame rate with video_fps, visual overlays with video_overlay, and encoding with video_codec.
Dwell time and trajectory tracking are advanced features enabled via dwell_time = true and trajectory = true.
Webhooks send real-time notifications when a person is detected; configure targets in webhook_targets and define each webhook under [webhooks].
Detection Zones exclude unwanted areas; upload a zone mask at the Plate Recognizer Account page or create one manually.

Hierarchical Configuration​

Parameters​

active​

sample​

timezone​

url​

Output Formats​

csv_file​

jsonlines_file​

image_format​

video_format​

video_before​

video_after​

video_fps​

video_overlay​

video_codec​

Advanced Parameters​

dwell_time​

max_dwell_delay​

trajectory​

Webhook Parameters​

How Webhooks Are Sent​

Format and Fields​

webhook_targets​

webhook descriptors​

url (webhook)​

image​

image_quality​

video​

caching​

request_timeout​

header​

Other Parameters​

Detection Zone​

Editing Zone Files​

Removing Zone Files​

Detection Zone Files​

Summary​

Hierarchical Configuration

Parameters

active

sample

timezone

url

Output Formats

csv_file

jsonlines_file

image_format

video_format

video_before

video_after

video_fps

video_overlay

video_codec

Advanced Parameters

dwell_time

max_dwell_delay

trajectory

Webhook Parameters

How Webhooks Are Sent

Format and Fields

webhook_targets

webhook descriptors

url (webhook)

image

image_quality

video

caching

request_timeout

header

Other Parameters

Detection Zone

Editing Zone Files

Removing Zone Files

Detection Zone Files

Summary