BOX 3.2: adding and configuring a camera

Adding a camera

In the tree, click “Add camera”. The main form has the tabs “General information”, “Detectors”, “Observers”; the Detectors tab is not available for some source types.

General fields

A stream may have several address variants: the main stream, a secondary stream and different codecs. Obtain the address from the camera/VMS documentation. If it requires access credentials, enter them in the working system, but remove the secrets before including the address in a report or support request.

Additional parameters: JSON settings for one camera

The Additional parameters field stores processing settings for this camera as JSON. It may contain detection and event filters, video processing options and settings for individual algorithms. It is not a free-text notes field: a key only has an effect if the installed component supports it.

Applicability. The settings below come from BOX documentation, the media server test guide and completed development tasks. Some belong to specific modules or deployments. The same field in BOX 5.0 does not imply that every scenario consumes these keys: check which camera parameters its blocks read. A completed development task confirms a change, but does not prove that it is installed in every system release.

Minimum object size and event suppression

Example field contents:

{
  "size_filters": [
    {
      "labels": ["person"],
      "min_size_width": 70,
      "min_size_height": 70
    }
  ],
  "time_window": 10
}

This example applies the size rule to the person class and sets a ten-second suppression window. The values 70 and 10 come from a deployment example. They are not defaults and must be chosen for the scene and task. A size filter can remove small detections; a threshold that is too high can also remove a person in the distance. The precise suppression algorithm and the meaning of zero depend on the component that reads the setting.

The source manual states that camera settings take precedence over the preset. Do not assume that every custom scenario follows this rule: it may read the parameters differently or ignore them.

The face detector documentation uses the same size_filters structure with the classes mask_off, mask_viol and mask, and 70 × 70 pixel thresholds. In that example, both dimensions must exceed 70 pixels. Class names depend on the installed model.

Media server: decoding, frame rate and processing group

Example: limit one camera to two frames per second.

{
  "mediaserver": {
    "fps": 2
  }
}

A low value is useful for testing, but may be unsuitable for fast movement or brief events. After the test, set a frame rate that meets the analytics requirements. A media server limit does not replace the camera schedule or the LLM execution interval.

For an MJPEG stream, the guide specifies a GENERIC camera with software FFmpeg decoding:

{
  "mediaserver": {
    "decoder_use_ffmpeg": true,
    "decode_hardware_decode_enabled": false
  }
}

When combining settings, place them in one mediaserver object and preserve its existing keys. Do not create two root keys with the same name.

After saving, check that HLS plays correctly, colours and proportions are natural, and playback delay does not keep growing. An operations engineer can verify the processing group in the media server log messages Camera group is and Adding camera to inference. To confirm hardware decoding, the guide uses nvidia-smi -q -x and the decoder_util field.

The limit for all cameras is configured separately through the service environment variable DECODE_MAX_FPS. Its documented values are positive integers; 0 disables the limit, and the documented fallback when the variable is absent is 25. This is a server setting. For one camera, the documented JSON path is mediaserver.fps. Do not automatically apply the environment variable's zero behaviour to the JSON field.

Linked cameras and crane cabin position

Example of a cabin-position setting:

{
  "cabin_position": "DOWN"
}

Manage the links themselves through the system's linked-camera screen. When changing another setting, preserve links and camera_position if they are already present. The documented event_filter_seconds change concerns duplicate filtering by person ID and zone type. It does not set the event clip length or a universal interval for every detector.

Speed settings by vehicle class

The speed detector configuration uses a speed_table object. Each key is a class code and each value is a numeric speed setting. The documented example is:

{
  "speed_table": {
    "car_sedan_suv": 40,
    "bus": 30,
    "truck": 20
  }
}

The available description does not specify units, the comparison rule, allowed ranges or the behaviour for an omitted class. Do not present 40/30/20 as universal limits in km/h. First check the configuration contract and calibration of the installed speed detector.

Settings for individual modules

A completed development change confirms support for reading module settings from the camera's additional parameters. This is a way to supply parameters, not a universal key catalogue for all algorithms.

The activity module documentation describes activity_thresholds with the levels low, medium and high, using 10/20/50 as an example. A later change groups the settings under person_activity and adds aggregation by time or frame count: aggregation_by_time, time_seconds_aggregate and num_frames_aggregate. Camera settings take precedence over this module's configuration; missing settings fall back to that configuration.

Check the installed contract before copying the old aggregation example. The task description misspells the key as aggretation_params, while the implementation comments use aggregation_params. The example's 30-second period is not a reliable default either: the change history records a new default of 60 seconds. Confirm the nesting and values for the installed release. These sources do not define the units of the activity thresholds.

Other completed tasks mention early_send_on_zone_exit and controlling pose detection through camera parameters. The reviewed descriptions do not provide their complete JSON contracts. For RTSP sources with malformed SDP, support was added for the GStreamer property force-noncompliant-url, requiring GStreamer 1.24.7 or later. However, these sources do not establish the exact camera JSON key or nesting. Apply these options using the module's configuration contract, not a task title alone.

Other parameters found in configurations

The following keys appear in deployment examples. This table records their structure and actual example values. It does not define allowed ranges or recommend copying the entire configuration to every camera.

A completed development task confirms the motion-checking module. Its description does not establish the units of time_for_report or drop_after_time, threshold ranges, or how percent_frames_for_report is calculated. The key names alone are insufficient to determine those rules.

Entering and checking changes

1. Copy the current field contents before editing. Preserve unrelated keys when changing one setting.
2. Enter a JSON object with double quotes around keys and strings. JSON does not allow comments or a trailing comma after the last item.
3. Check the model's class codes and the units. Do not reuse pixel thresholds in a different view without checking the image scale.
4. If a separate editor is open, select Apply, then save the camera. Use controlled footage to compare required detections, small objects and repeated events before and after the change. For media server settings, also check HLS playback.
5. If required events disappear, restore the saved configuration and check the size filter, event suppression and interaction with the preset or scenario.

BOX 3.2 API: the reviewed CreateCamera.etc_params schema is string | null, with the default "{}". The field's JSON must therefore be sent as a string with escaped quotes, for example "etc_params": "{\"time_window\":10}". This is a request-body fragment, not a complete camera creation request. An empty object means that no keys are set here; it does not define universal analytics defaults.

If the field is unavailable: check permission to edit the camera and its additional parameters. A project-specific role model was extended to give administrators and data analysts access, including for synchronised cameras. Your installation's permissions determine actual access. If the button does not open the editor, or existing values disappear when editing, record the interface version and contact support: this behaviour has been documented and fixed as a defect. Do not save an empty form over a configured camera.

Camera types and their specific fields

Changing the type changes the available fields. Select the type first, then enter the address and type-specific parameters. Do not enter internal API enumeration values in the name field or copy them from hidden interface elements.

“Detectors” tab

Click “Add preset”, and select an existing preset. Rows can be deleted or moved. Review the resulting set of classes and save the camera. Do not add the same preset more than once. For full descriptions of thresholds and states, see §9.5.

“Observers” tab

Find and select the user, then click “Add”. Check the entries already added: the creator may already be listed. Save. An observer is responsible for the camera and participates in the notification route; their actual access is also governed by their role.

Checks after saving

1. Find the camera under the correct site.
2. Open the live stream and make sure the view is correct and the image is updating.
3. Check the camera status and neural network status separately.
4. Open the zones and make sure their boundaries match the frame.
5. Check the expected detection and log entry using an approved test example.
6. If recording is enabled, check the archive separately.
7. Open the camera using the operator’s working role.

Copying a camera does not replace these checks: verify the new camera’s address, site, zones, presets, observers and schedule. Preset saving/copying was fixed in closed issues BOXD-5278 and BOXD-5285; this is a reason to check the result, not a guarantee that every copy is automatically correct.

Camera card: all tabs

Open the card from monitoring or the tree. Common actions are back, “Edit”, and location on the map if a plan is available. Eight tabs were available on the inspected camera.

First distinguish a video acquisition problem from a neural network processing problem. A healthy stream produces no new detections while analytics are disabled. Activity history helps establish whether a shutdown was scheduled or manual.

There is a Jira proposal for a “Parameters” tab (BOXD-5321), but this tab is absent from the inspected card. It is therefore not included in these instructions as an available feature.

On screen: Example of an open archive recording and clip list; Diagnosing missing recordings; Diagnosing playback errors.

Choosing HLS or WebRTC for live viewing

Applies to: BOX 3.2 camera cards with an HLS / WebRTC selector on the Live stream tab. You need permission to view the camera, a working video source, and a deployment configured to deliver the selected stream to your browser. If the selector is absent, ask your administrator which viewing modes the installed interface and integration support.

This selector changes how video reaches the browser. The camera connection address and source protocol are configured separately. Switching between HLS and WebRTC does not enable archive recording or start a disabled detector.

1. Open the camera card from monitoring or the camera tree, then select Live stream.
2. Keep the same Camera or Neural network view when comparing modes. Select HLS or WebRTC and start playback if paused.
3. Check that the image updates and assess the delay. If the problem persists, compare the other mode on the same camera.
4. Check the archive and analytics state separately. Successful playback alone does not prove that recording or analysis is running.

Expected result: a viewing mode that suits the task, with a current image and a delay the operator understands. WebRTC is generally the first choice when responsiveness matters; HLS is an alternative when playback is unstable. A fixed delay or universal processing-load advantage is not guaranteed: source, server, network and browser conditions affect the result.

If HLS works but WebRTC does not, give your administrator the time, camera identifier, browser version and comparison result. Changing the camera RTSP address or analytics settings is not part of switching the viewing mode. If many cameras fail together, use the shared-failure checks.