Skip to main content

Stream - FAQ

📋 General Requirements​

Do I need an internet connection to install and run Stream?​

Yes and no.

For our standard implementation, you will need an internet connection to install or update Stream. After installation, a Stream subscription will "call home" a few times a month to validate the license. No images are sent; only a few bytes of data are transmitted to confirm the subscription. Therefore, a flaky or intermittent internet connection is acceptable for the Stream Subscription License.

If you have no internet access, you can opt for a Perpetual License of Stream. Please contact us for more information about this licensing option.

To install Stream without an internet connection, please contact us for details.

💻 Installation & Deployment​

How do I install Stream on Windows using Docker?​

We recommend using the Plate Recognizer Installer to install Stream. You can download the Plate Recognizer Installer from our website.

If you prefer to install via Docker, please refer to our Docker help page for guidance.

caution

If you are running Windows as a virtual machine, either on-premise or in the cloud, ensure that it supports nested virtualization. Otherwise, you will not be able to run Docker, and consequently, Stream will not work.

Can I deploy Stream on AWS, Azure, or Google Cloud?​

Yes, Stream can be deployed on any major cloud provider, including Amazon Web Services (AWS), Microsoft Azure, and Google Cloud Platform (GCP).

If you plan to use a Windows-based instance, please review the caution note above.

How do I start Stream for Thailand and Jetson devices?​

To get started with Stream on Thailand-optimized or Jetson devices, please refer to the list of additional Docker images for Stream, which includes specific builds tailored for these platforms.

I can't install Stream on new hardware.​

Stream creates a digital fingerprint of your device's specifications. If you change a hardware component, Stream will stop working. Please contact us to request a reset of your Stream Subscription License. Note that we are unable to reset Perpetual Licenses.

How can I update to a new version of Stream?​

Please refer to our guide on updating to a new version of Stream.

How do I completely uninstall Stream?​

To uninstall Stream, remove the Docker image with the following command:

docker image rm platerecognizer/alpr-stream

Note that the license will remain tied to the original device.

Please contact us to remove the fingerprint after you have uninstalled Stream.

⚙️ Configuration & Optimization​

How do I set the FPS in Stream to optimize hardware?​

By default, Stream processes every other frame. For example, if your camera captures at 60 FPS, Stream will process approximately 30 frames per second. Unless vehicles are moving at high speeds, processing 30 FPS is usually unnecessary.

Based on vehicle speed, we recommend setting the effective FPS (eFPS) as follows:

  • For vehicles traveling under 30 mph, set eFPS to 4–5.
  • For vehicles traveling between 30 and 60 mph, set eFPS to 8–10.
  • For vehicles traveling over 60 mph, set eFPS to 12.

To calculate eFPS, divide the camera's FPS by the sample rate configured in Stream. For example, if your camera records at 30 FPS and you set sample=6, your effective FPS will be 5.

We recommend testing and adjusting these settings according to your specific environment. If you need assistance, feel free to contact us.

Will Stream accuracy improve if I increase max_prediction_delay?​

The impact on accuracy depends on the environment:

  1. In a parking scenario where the camera can clearly see the license plate from a distance as the vehicle approaches, there is likely no meaningful difference in ALPR accuracy.

  2. However, in cases where the camera's view of the plate is obstructed or the camera has a lower resolution, increasing max_prediction_delay gives Stream more time to find the best frame for optimal ALPR results.

As always, we encourage you to test this parameter and compare the results in your specific environment.

What is the minimum value for max_prediction_delay?​

The minimum value is 0.1 seconds.

However, we do not recommend setting it to 0.1, because Stream may not have a clear image of the license plate when it first spots the vehicle, which could lead to an incorrect decoding.

Unless you require a very fast real-time result (e.g., to open a gate), we recommend keeping this parameter at its default value.

What is the minimum value for the memory_decay parameter in Stream?​

The minimum value is 0.1 seconds.

However, for clarity, we do not recommend setting it this low, because if the camera sees the same vehicle again (e.g., 0.2 seconds later), Stream will count it as a new vehicle in the ALPR results.

What does the Stream Health Score mean?​

The Stream Health Score is a measure of Stream's performance on its host hardware.

If the Health Score is below 70%, the machine is not fast enough, and there is a higher chance that Stream will miss license plates.

Below are some possible remedies:

  • Upgrade to a faster machine. See our Stream Hardware Recommendations.
  • Ensure that no other compute-intensive programs are running.
  • Reduce the number of cameras in Stream.
  • Lower the camera feed resolution (this is done outside of Stream).
  • Increase the sample parameter in config.ini. If the value is too high, Stream may miss license plates.

How can I prevent Stream from monopolizing the CPU when running multiple containers on the same machine?​

When running multiple containers alongside Stream, it is crucial to ensure a fair distribution of processing power. You can use Docker Runtime Options to limit Stream's CPU usage.

For example, you can run Stream with a CPU limit like this:

docker run ... --cpus=1.5

This setting guarantees that the container will use at most 1.5 CPUs. If your host machine has 2 CPUs and you specify --cpus=1.5, Stream will be limited to one and a half CPUs, leaving resources available for other containers.

What is the real benefit of using a GPU in Stream?​

The GPU is used to accelerate inference, which is the process where Stream analyzes and interprets video data, such as object recognition or pattern detection. This acceleration enables increased parallelism, meaning the system can process a larger number of cameras simultaneously, significantly improving the overall throughput (processing capacity).

Does using the GPU mean Stream stops using the CPU?​

No. Although the GPU accelerates inference, other important video processing tasks—such as decoding, encoding, and object tracking—are still performed by the CPU. Therefore, CPU usage remains present and can be significant depending on the workload. The GPU complements the CPU but does not fully replace it in Stream's processing.

🔐 Licensing & Activation Issues​

What does the error "License file not found for Stream installation" mean?​

This error indicates that the system does not recognize the API Token or License Key for Stream.

Please double-check your API Token and License Key and ensure that the device has an internet connection.

What does the error "This license has already been used" mean?​

This error message indicates that the license has already been used. We permit only one Stream license to be installed on a single machine. To resolve this issue, please uninstall the license from the previous machine before installing it on a new one.

If you have a Subscription for your Stream license, go to your Account Page and click Manage > Reset for the specific license key. If you have a Perpetual License, please note that we are unable to recover the license key, as stated in our Terms for Perpetual License.

What do I need to do after adding additional camera licenses to my Stream license?​

After adding camera licenses or making other configuration changes to Stream—such as modifying detection zones, updating webhooks, or changing configuration parameters—you must restart the Stream container to apply the changes.

For instructions on how to restart, please refer to our guide on managing Docker containers.

🛠️ Error Messages & Troubleshooting​

How do I resolve the error Connection to tcp://192.168.0.111:8080?timeout=0 failed: Connection refused?​

This error indicates that Stream cannot connect to the camera at the specified IP address and port. This typically means the camera is offline, misconfigured, or not accepting connections on that port.

For detailed troubleshooting steps, refer to the guide on resolving camera connection issues.

What should I do if Stream does not correctly decode an image?​

The premise for Stream to work is that the license plate is identifiable by the naked eye in the video. It does not need to be perfectly clear, but if it is not possible to identify the plate visually, the system will not be able to decode it.

If you believe the plate is visible enough in your video but Stream still fails to decode it correctly, please contact our support team. To better assist you, please provide a 30-second video clip demonstrating the issue. We will be happy to review it and help resolve the problem.

What does the error message "There is a drop in performance" mean in Stream?​

The "Drop in performance" message appears when Stream is running out of resources and struggling to process the video or live camera feed. This typically occurs when CPU or memory utilization exceeds 90%.

To resolve this, allocate more RAM and CPU to Docker. You can refer to the Stream Hardware Recommendations for guidance.

How can I configure Stream to process a camera or video feed?​

Please refer to the Stream Configuration guide for instructions.

What does the error message "Stream periodically 'pings home' to validate the subscription. Please provide Internet connectivity and re-run the Docker command to reactivate Stream" mean?​

This error indicates that the Stream service could not connect to the server to authenticate the license. This can happen if the device lacks internet connectivity, particularly to our servers, or if the Docker container's networking configuration blocks internet access.

To resolve this, ensure that Docker can connect to our servers. You can verify this by following the steps outlined here. If you are certain that access is allowed, run the Stream container with host networking using the --network host flag.

How do I get the Stream version?​

You can get the Stream version by accessing the Docker container logs. To do this, you'll need your Stream container's ID or name. If you don't know what it is, you can list them with the following command:

docker ps

After identifying your container's ID or name, use one of the commands below, depending on your operating system:

  • On Windows (PowerShell): 
    docker logs <your_Stream_container_ID_or_name> | Select-Object -First 1
  • On Linux/macOS: 
    docker logs <your_Stream_container_ID_or_name> | head -n 1

The output will be something like:

INFO:root:Plate Recognizer Stream v1.57.0

📷 Camera Connectivity​

How can I connect Stream to a camera through a DDNS server?​

To connect your camera via a DDNS (Dynamic DNS) server, you first need to configure port forwarding on your router to allow external access to the camera's stream.

Once port forwarding is set up, you can use a URL in the following format to connect Stream to your camera via DDNS:

rtsp://admin:password@<your-ddns-domain>:<port>/stream-path

Make sure to replace <your-ddns-domain>, <port>, and /stream-path with your actual DDNS domain, forwarded port number, and the correct camera stream path.

If you need help with router configuration or finding the correct stream URL, consult your camera's manual or contact your network administrator.

What happens if the camera is accidentally turned off or resets?​

Stream will automatically reconnect with the camera when it is turned back on. See max_reconnection_delay for more information.

What should I do if Stream is unable to connect to a camera?​

  1. Verify the Camera Stream First, ensure that your camera is streaming correctly. You can do this by opening the RTSP URL in a media player such as VLC or ffplay.

  2. Try a Different Transport Protocol Some cameras require a specific protocol for RTSP. You can try forcing UDP by including this environment variable in your Docker run command:

    -e OPENCV_FFMPEG_CAPTURE_OPTIONS="rtsp_transport;udp"

    Example Docker Run Command with UDP Option

    sudo docker run --rm -t --name stream \
    -v /home/kyt/documents/stream:/user-data \
    --user $(id -u):$(id -g) \
    -e LICENSE_KEY=XXXXX \
    -e TOKEN=YYYYY \
    -e OPENCV_FFMPEG_CAPTURE_OPTIONS="rtsp_transport;udp" \
    platerecognizer/alpr-stream

  3. Still Not Working?

    If the problem persists, please contact us and include the make and model of your camera. This will help us provide more targeted support.

The RTSP URL works fine in VLC, but Stream can't connect to it. What should I do?​

This issue commonly occurs with Milestone Open Network Bridge after their 2021 R1 update, which added SHA256 as a digest authentication method. The problem is that Stream does not support servers that offer both MD5 and SHA256 for digest authentication at the same time, while VLC is compatible.

Symptoms:

  • RTSP URL works perfectly in VLC Media Player
  • Same URL fails to connect when used in Stream
  • Testing the same URL with ffplay might not work, giving 401 Unauthorized

Solutions: A Registry edit for Milestone ONB (Windows) is required, so Stream will only see MD5 algorithm for authenticating with ONB.

warning

Registry editing can be dangerous. Always back up your registry before making changes.

  • Press Win + R, type regedit, and press Enter
  • Navigate to: HKEY_LOCAL_MACHINE\SOFTWARE\Milestone\Milestone Open Network Bridge\
  • Right-click in the right panel and select New > DWORD (32-bit) Value
  • Name it: SHA256Auth
  • Set the value to 0
  • Restart your Milestone ONB service or reboot the computer

Testing the Fix: After applying any of the above solutions, test the RTSP URL with ffplay. Use the following command:

ffplay -rtsp_transport tcp rtsp://username:password@ip:port/path

If it works, you can now test the same URL with Stream to confirm the connection works consistently across both applications.

If it didn't work, please contact our support team with details about your VMS system, and the troubleshooting steps you've tried.

What does the error message "Stream failed to register camera" mean?​

This message indicates that Stream was unable to contact our servers to register the camera. This can happen if the device cannot access the internet or if the Docker container's networking configuration does not allow internet access.

To resolve this issue, ensure that Docker can connect to the internet. You can also try running the container with host networking by using the –network host flag.

🐳 Docker Management​

How do I manage a Docker container?​

Below is a summary of basic Docker commands:

  • docker ps: Lists running containers.
  • docker stop <container_name_or_id>: Stops a running container.
  • docker rm <container_name_or_id>: Removes a container.
  • docker start <container_name_or_id>: Starts an existing container.
  • docker restart <container_name_or_id>: Restarts a container.

Example command to restart Stream:

docker restart stream

🎞️ Video Source​

Can Stream process a video file instead of a camera feed?​

Yes, Stream can analyze both live camera feeds and video files. For more details, please refer to our guide on processing video files.

What types of video files can Stream accept?​

Stream supports all video formats compatible with FFmpeg.

How can I set up Stream to process a video file?​

Stream works with all video formats supported by FFmpeg, including common formats like .mp4, .avi, .mkv, and .mov.

To process a video file with Stream, please follow the steps in our guide on how to process a video file on Stream.

How long does it take for Stream to analyze a video file?​

The analysis time depends on multiple factors including CPU PassMark rate, number of cores, memory speed, and the sample rates set in the Stream configuration.

The following table shows the results of several tests we conducted on the same two-hour video file to establish a benchmark:

PassMarkSample=1Sample=2Sample=4Sample=8
~8,00019m18m16m16m
~12,00018m17m16m18m
~17,00016m14m14m13m

Video configuration used in tests:​

  • Codec: MPEG-H Part2/HEVC (H.265)
  • Resolution: 1440 × 1080
  • Frame rate: 30 FPS
  • Duration: 2 hours

Important: PassMark score is just one indicator of performance. Modern CPUs (2020+) with better single-thread performance, more efficient architectures, and higher core counts often outperform older CPUs with similar or even higher PassMark scores. We recommend testing different sample rates on your specific hardware to find the optimal configuration.

Recommendations​

  • Test on your hardware: The optimal sample rate varies significantly between different CPU models and architectures
  • Monitor your system: CPU usage, available memory, and disk I/O can all impact processing time
  • Consider other factors: Available RAM, disk speed (SSD vs HDD), and background processes also affect performance

How do I test a camera's RTSP stream in VLC?​

RTSP (Real-Time Streaming Protocol) allows for real-time video streaming and is commonly used in security cameras. VLC Media Player is an excellent tool for quickly testing and playing these streams.

  1. Download VLC

    Go to the official videolan.org/vlc website to download and install VLC for free.

  2. Set Up RTSP in VLC

    • Open VLC and go to Media/File > Open Network Stream/Open Network.
    • Enter the camera's RTSP URL (e.g., rtsp://username:password@camera_ip:port/path).
    • Click Play to start streaming.

    If everything is configured correctly, VLC will display the camera's live video, allowing you to check the connection and stream quality.

How do I check the stream quality (FPS, resolution) in VLC?​

To verify details such as frame rate (FPS), resolution, and bitrate of the RTSP stream in VLC, follow these steps:

  1. Start Playing the Stream

    Follow the steps in the previous section to open the stream in VLC.

  2. Open Codec Information

    • With the stream playing, go to Windows > Media Information (or press Ctrl + J on Windows or Cmd + I on macOS).
    • In the Codec details tab, you will find information such as video resolution, frame rate (FPS), and codec type.

  3. View Stream Statistics

    • For more detailed information, go to Windows > Media Information > Statistics.
    • Here, you will see data on input bitrate, dropped frames, and other live metrics that indicate the stream's quality.

These options will help you analyze the video quality, performance, and stability of the RTSP stream directly in VLC.

📤 Stream Output​

How do I get the timestamp of vehicles captured in Stream when processing videos?​

We provide the timestamp of the video in the position_sec field, which corresponds to when the vehicle plate was identified in the video.

  • When the input is a video file, position_sec is the number of seconds from the beginning of the video.
  • When the input is a camera, position_sec is the number of seconds since Stream started.

What is the output of Stream?​

Stream generates the following types of output:

  1. CSV File: A .csv file containing all ALPR (Automatic License Plate Recognition) results.
  2. JSON File: You can save the ALPR results to a .jsonl (JSON Lines) file using the jsonlines_file option.
  3. Camera Screenshots: Images captured at the moment of each detection.
  4. Webhooks: Each ALPR result and its associated image(s) can be sent via webhook to your system.
  5. Video Clips: You can configure Stream to save short video clips of detected vehicles by setting the video_format parameter.

How can I get more log output from Stream?​

You can increase the log output from Stream by adding the LOGGING environment variable.

Here are the available levels:

  • 10 for debug
  • 20 for info
  • 30 for warning

Example:

docker run ... -e LOGGING=10

Is there a way to add visualizations of plate results to a video?​

Yes! You can add overlays such as bounding boxes, timestamps, and vehicle information directly to the video output using the video_overlay parameter.

This makes it easier to understand how Stream is working and helps in troubleshooting or fine-tuning your configuration.

See the video_overlay section in the configuration reference for all available options and setup instructions.

Can I remove older images from the Stream output?​

Yes! You can use a script to remove images that are older than a specified number of hours from your Stream folder.

Please refer to the Stream Images Removal Script for the script and setup instructions.

Where are my Stream output files saved?​

By default, all output files are saved in the main Stream directory (where your config.ini is located).

How can I organize my output files into custom folders?​

You can organize files by editing these parameters in your config.ini:

  • csv_file: CSV data files
  • jsonlines_file: JSON Lines data files
  • image_format: Image snapshots
  • video_format: Video clips

Organization Strategies:

By file type:

csv_file = output/csv/$(camera)_%y-%m-%d.csv
jsonlines_file = output/json/$(camera)_%y-%m-%d.jsonl
image_format = output/images/$(camera)_%y%m%d_%H%M%S.jpg
video_format = output/videos/$(camera)_%y-%m-%d_%H-%M-%S.mp4

By camera:

csv_file = output/$(camera)/data.csv
jsonlines_file = output/$(camera)/data.jsonl
image_format = output/$(camera)/%y-%m-%d_%H-%M-%S.jpg
video_format = output/$(camera)/videos/%y-%m-%d_%H-%M-%S.mp4

By date:

csv_file = output/%y-%m-%d/$(camera)_data.csv
jsonlines_file = output/%y-%m-%d/$(camera)_data.jsonl
image_format = output/%y-%m-%d/$(camera)_%H-%M-%S.jpg
video_format = output/%y-%m-%d/$(camera)_%H-%M-%S.mp4

How do I customize output filenames?​

You can use dynamic variables and date/time formatting in your filename patterns:

Dynamic Variables:

  • $(camera): Camera name (e.g., camera-1)

Date/Time Formatting:

  • %y-%m-%d: Date (e.g., 25-06-03)
  • %H-%M-%S: Time (e.g., 20-54-35)
  • %f: Microseconds

Date/time formatting follows strftime.org standards.

info

The date and time formatting depends on the timezone parameter configured in Stream. For example, if you set timezone = US/Central, all file names generated using this format will reflect that timezone. Be careful when configuring this parameter, as an incorrect timezone may cause files to be saved in unexpected date- or time-stamped directories, making them difficult to locate.

Examples:

# Timestamp with microseconds
image_format = screenshots/$(camera)_%y-%m-%d_%H-%M-%S.%f.jpg

# Hourly folders
csv_file = logs/%y-%m-%d/%H/$(camera)_detections.csv

# Camera and date combined
jsonlines_file = data/$(camera)_%y-%m-%d_results.jsonl

How can I save Stream output to an external USB drive or SD card?​

Yes, you can save Stream output to external storage devices like USB drives or SD cards. Follow these steps:

Step 1: Mount the External Drive

First, identify and mount your external drive:

# Check available drives before and after plugging in your device
lsblk

# Create a mount point if it doesn't exist
mkdir -p /media/<username>/sdcard

# Mount the drive (replace /dev/sdXY with your actual device)
sudo mount -t vfat -o uid=$(id -u),gid=$(id -g) /dev/sdXY /media/<username>/sdcard
note

This assumes your external drive is formatted as FAT32. If it's formatted differently, adjust the -t parameter accordingly.

For SD cards, the device will appear as /dev/mmcblk1p1 instead of /dev/sdXY.

Step 2: Bind the Mount Point to Stream Container

Add a volume mount to your Stream Docker command:

# Original command
docker run --restart=unless-stopped -t --name stream \
  -v "/home/<username>/stream":/user-data \
  -e LICENSE_KEY=XXXXXXXX -e TOKEN=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy \
  platerecognizer/alpr-stream

# Add the external drive mount
docker run --restart=unless-stopped -t --name stream \
  -v "/home/<username>/stream":/user-data \
  -v /media/<username>/sdcard:/mnt/usb \
  -e LICENSE_KEY=XXXXXXXX -e TOKEN=yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy \
  platerecognizer/alpr-stream

Step 3: Configure Stream to Use External Storage

Update your config.ini to save output files to the external drive:

image_format = /mnt/usb/$(camera)_screenshots/%y-%m-%d/%H-%M-%S.%f.jpg
video_format = /mnt/usb/$(camera)_videos/%y-%m-%dT%H-%M-%S.%f.mp4
csv_file = /mnt/usb/$(camera)_%y-%m-%d.csv
# jsonlines_file = /mnt/usb/$(camera)_%y-%m-%d.json

You're free to save just videos to external storage by commenting out the other lines. This will save you space on the external drive. You can also set different paths for each camera by using the $(camera) variable. Refer to Stream configuration guide for full details.

warning
  • File System Limitations: FAT32-formatted drives may not support Unix permissions. The user who mounts the drive will own the files.
  • Symbolic Links: Symbolic links created outside the container will not work due to Docker's filesystem isolation. Direct volume mounting is required instead.
  • Auto-mounting: Desktop environments often auto-mount drives to /media/<username>/<drive-label>. Use the actual mount point from your system.

🔁 Webhooks​

Why does it seem like Stream sends the webhooks with a few seconds delay?​

There may be a few reasons for this delay:

  1. The internet connection speed may be slow. If this is the case, then try sending the webhooks without an image.

  2. The hardware running Stream may be running at out of resources. Verify this by looking at the RAM and CPU utilization at times when the webhooks seem to be delayed. If this is the case, then you will need to get a stronger machine.

  3. Perhaps the webhook target or receiver is slow in processing the requests. You can verify this by sending the webhooks to a different target such as https://webhook.site/

  4. The delay is also dependent on max_prediction_delay parameter. This parameter sets the maximum delay in seconds before a prediction is returned. Note that reducing it may lower recognition accuracy.

As always, we encourage you to examine and test the items above to see if you can increase the time to receiving the webhooks.

How often does Stream try to resend webhooks?​

Refer to our Stream configuration guide for more details about webhooks.

If the server does not respond or produces an error, the prediction is discarded.

What does the timestamp in Stream webhooks refer to?​

The timestamp refers to when the vehicle is detected and when a plate is read.

Here's an example: – Stream detects a vehicle at time 001 but the license plate is not visible. – Stream detects a vehicle at time 003 and the license plate is readable. – The timestamp in the webhook JSON will be 003.

What does this error message mean: "Webhook queue is full"?​

If you get this message, it means the webhook queue has reached a size of 100 and is now filled up. This is caused by the receiving server being too slow as a result of connectivity issues. When the queue is full, the new results are dropped and won't be sent to the webhook_target.

To resolve this issue, you should optimize your webhook receiving server to be able to quickly process the requests.

How do I test or troubleshoot Webhooks in Stream?​

The easiest way is to first test whether the ALPR events are being sent out to https://Webhook.site. Refer to our Stream configuration guide for details.

To receive the Webhooks, please refer to this Script that we created specifically for Webhooks with Plate Recognizer in these programming languages: Python, Flask, Javascript/Node, C#.

Please note that the bounding boxes in the webhook are different when you use the "webhook_image = true" option. When this is turned on, the cropped vehicle image is sent along with the webhook data. The bounding boxes then refer to the position in the cropped image and not the full source image.

If you would like the original bounding boxes, you can set "webhook_image = false" or you can recover the original bounding box using the vehicle bounding box. For example:

obj['box']['xmin'] += obj['vehicle']['box']['xmin']

How can I improve webhooks speed of the ALPR results?​

To decrease the time required for webhooks, you can try to (a) exclude images from the webhooks, or (b) put the webhook target/receiver on the same HOST as Stream to minimize network latency.

How do I not save vehicle or plates images in my local Stream folder when forwarding webhook data?​

To not save images locally, do not set either csv or jsonlines as output in the configuration file. For example:

[[camera-1]]
     active = yes
     url = rtsp://localhost:8554/live
     #csv_file = $(camera)_%y-%m-%d.csv
     webhook_targets = parkpow