brainframe-apps¶

brainframe-apps is a set of command line tools that manage a BrainFrame server through its REST API. Use it to add and remove streams, start and stop analysis, manage zones, alarms, and capsules, process images, read live zone statuses, and back up or restore the server's configuration. Because it uses the REST API, it can manage a server on the same machine or on another machine.

Installation¶

pip install brainframe-apps

Requires Python 3.9 or newer (tested on Python 3.10).

Usage¶

brainframe-apps <command> [options]

To list the options of a command, run brainframe-apps <command> --help.

Commands¶

Command	Purpose
`add-stream`	Add IP camera streams or a video file to BrainFrame.
`delete-stream`	Delete streams from BrainFrame.
`list-stream`	List the streams on the server.
`start-analyzing`	Start AI analysis on streams.
`stop-analyzing`	Stop AI analysis on streams.
`get-zone-statuses`	Show live zone statuses, detections, and alarms.
`process-image`	Run the server's capsules on an image file.
`capsule-control`	List, load, enable, disable, unload, and configure capsules.
`zone-control`	List, add, delete, save, and load zones.
`alarm-control`	List, add, delete, save, and load alarms.
`identity-control`	List, add, and delete identities.
`license-control`	Show or set the server license.
`user-control`	Sign in a user of a BrainFrame cloud deployment.
`save-settings`	Save the server's configuration to a file.
`load-settings`	Restore a saved configuration to a server.

Common Options¶

Most commands accept these options:

Option	Description
`--server-url SERVER_URL`	The address of the BrainFrame server. Default: `http://localhost`.
`--stream-url STREAM_URL`	Act on one stream, identified by its URL. For a video file, use its storage ID.
`--stream-urls STREAM_URLS`	Act on the streams listed in a file. Default: `stream-urls.csv`.

If the server is not on the machine where you run the command, set --server-url, for example --server-url http://192.168.1.50.

Warning

Commands that take a stream list read stream-urls.csv from the current directory when it exists, and act on those streams. If the file does not exist and you give no --stream-url, some commands act on all streams on the server. This is how delete-stream deletes every stream. Check which directory you are in before you run it.

The Stream List File¶

The stream list is a CSV file with one stream per line. This is the same format as the config.csv file written by brainframe-onvif-tools, so you can pass that file with --stream-urls config.csv.

Only lines that contain an rtsp:// URL are used. Blank lines and lines starting with # or < are ignored.
The first value that starts with rtsp:// is the stream URL.
The value after the URL is the stream name. If it is empty, the URL is used as the name.
The value after the name is optional stream options as JSON, for example a custom pipeline.
The word localhost in a line is replaced with this machine's IP address.

rtsp://admin:PASSWORD@192.168.1.10:554/stream1,Front Door
rtsp://admin:PASSWORD@192.168.1.11:554/stream1,Back Door

Managing Streams¶

add-stream¶

Adds streams to BrainFrame. Choose one source:

# Add every stream in a list file
brainframe-apps add-stream --stream-urls config.csv

# Add one IP camera
brainframe-apps add-stream --stream-url rtsp://admin:PASSWORD@192.168.1.10:554/stream1 --stream-name "Front Door"

# Upload a video file from this machine and add it as a stream
brainframe-apps add-stream --video-file video.mp4

Option	Description
`--stream-urls STREAM_URLS`	A file listing the streams to add. Default: `stream-urls.csv`.
`--stream-url STREAM_URL`	The URL of one stream to add.
`--stream-name STREAM_NAME`	The name of the stream added with `--stream-url`. Default: the URL.
`--video-file VIDEO_FILE`	A video file to upload and add.

delete-stream¶

Deletes streams from the server.

# Delete one stream
brainframe-apps delete-stream --stream-url rtsp://admin:PASSWORD@192.168.1.10:554/stream1

# Delete the streams in a list file
brainframe-apps delete-stream --stream-urls config.csv

Warning

If no stream list file exists in the current directory and you do not give --stream-url, delete-stream deletes all streams on the server.

list-stream¶

Lists the streams on the server.

brainframe-apps list-stream
brainframe-apps list-stream --show-capsules

Option	Description
`--show-capsules`	Also show each stream's capsules.

start-analyzing and stop-analyzing¶

Start or stop AI analysis on streams. With no stream specified, they act on the streams in stream-urls.csv if the file exists, and otherwise on all streams.

brainframe-apps start-analyzing
brainframe-apps stop-analyzing
brainframe-apps start-analyzing --stream-url rtsp://admin:PASSWORD@192.168.1.10:554/stream1

Option	Description
`--keyframe-only`	Analyze only keyframes of the stream.

Reading Results¶

get-zone-statuses¶

Shows live zone status from the server. For each stream it reports the detections in each zone, entering and exiting objects, and alarm activity.

brainframe-apps get-zone-statuses
brainframe-apps get-zone-statuses --stream-id 3 --detection person --zone Screen

Option	Description
`--stream-id STREAM_ID`	Show only this stream.
`--detection DETECTION`	Show only these detection classes, as a comma-separated list, for example `person,chair`.
`--zone ZONE`	Show only these zones, as a comma-separated list, for example `Screen,LINE_DESK`. Default: all zones.
`--alarm ALARM`	Show only these alarms, as a comma-separated list.
`--n-samples N_SAMPLES`	The number of recent samples to keep. Default: 100.
`--alert-totals-interval SECONDS`	How often to refresh each zone's total alert count. Default: 10.
`--time`	Include the `time` and `timestamp` columns in each line.
`--capture-events FILE`	Write zone status records that contain entering, exiting, or alert activity to this file, for diagnosis.
`--capture-limit CAPTURE_LIMIT`	With `--capture-events`, stop after this many records. Default: 20.

process-image¶

Runs the capsules enabled on the server on a PNG image, and draws the detections on the image. It uses the capsule configuration of one stream when you specify it, and otherwise the server's global capsule configuration.

brainframe-apps process-image --image-path frame.png
brainframe-apps process-image --image-path frame.png --stream-id 3

Option	Description
`--image-path IMAGE_PATH`	The PNG image to process. Required.
`--stream-id STREAM_ID`	Use the capsules enabled on this stream.
`--stream-url STREAM_URL`	Use the capsules enabled on the stream with this URL.

The annotated image is saved next to the original, with _detections added to the name. For example, frame.png produces frame_detections.png. The command also opens the image in a window, so it needs a graphical display. Press q in the window to exit.

Configuring the Server¶

capsule-control¶

Manages the capsules on the server.

# List streams and their capsules
brainframe-apps capsule-control --cmd list

# Upload and load a capsule file from this machine
brainframe-apps capsule-control --cmd load --capsule-filename my_capsule.cap

# Enable or disable a capsule, on the whole server or on one stream
brainframe-apps capsule-control --cmd enable --capsule-name detector_person
brainframe-apps capsule-control --cmd disable --capsule-name detector_person --stream-id 3

# Set capsule options, as JSON. The option names depend on the capsule.
brainframe-apps capsule-control --cmd configure --capsule-name detector_person --options '{"OPTION_NAME": VALUE}'

Option	Description
`--cmd CMD`	One of `list`, `load`, `unload`, `enable`, `disable`, or `configure`. Default: `list`.
`--capsule-name CAPSULE_NAME`	The capsule to act on. For `enable`, `disable`, and `unload`, omitting it applies the command to all capsules.
`--capsule-filename CAPSULE_FILENAME`	The capsule file to load. Used with `load`.
`--options OPTIONS`	The capsule options as a JSON string. Used with `configure`.
`--stream-id STREAM_ID`	Apply the command to this stream only. Otherwise it applies globally.

zone-control¶

Manages zones and lines on streams. Identify the stream with --stream-id, --stream-name, or --stream-url.

The zone definition for add is a JSON object. coords is a list of [x, y] pixel positions in the stream's frame. A line has two points, and a zone can have three or more. Set alarms to an empty list and id to null. Add alarms afterwards with alarm-control.

brainframe-apps zone-control --cmd list
brainframe-apps zone-control --cmd add --stream-id 3 --zone-name ZONE-Door \
    --options '{"coords": [[0, 0], [640, 0], [640, 720], [0, 720]], "alarms": [], "id": null}'
brainframe-apps zone-control --cmd delete --stream-id 3 --zone-name ZONE-Door

# Save all zones to a file, and restore them later
brainframe-apps zone-control --cmd save --file zones.json
brainframe-apps zone-control --cmd load --file zones.json

Option	Description
`--cmd CMD`	One of `list`, `add`, `delete`, `save`, or `load`. Default: `list`.
`--stream-id`, `--stream-name`, `--stream-url`	The stream to act on.
`--zone-name ZONE_NAME`	The name of the zone to add or delete.
`--options OPTIONS`	The zone definition as a JSON string. Required for `add`. It must contain `coords`, `alarms`, and `id`.
`--file FILE`	The file to save to or load from. Default: `zones.json`.

alarm-control¶

Manages the alarms of zones. Alarms belong to a zone, so identify both the stream and the zone.

In the example below, the alarm triggers when more than zero people are in the zone for at least half of a 5-second window. test can be >, <, =, or !=. intersection_point is the point of each detection that must be inside the zone: bottom, top, left, right, or center. To copy an existing alarm, save the alarms to a file and look at its contents.

brainframe-apps alarm-control --cmd list
brainframe-apps alarm-control --cmd add --stream-id 3 --zone-name ZONE-Door --alarm-name ALRM-person \
    --options '{"count_conditions": [{"test": ">", "check_value": 0, "with_class_name": "person", "with_attribute": null, "window_duration": 5.0, "window_threshold": 0.5, "intersection_point": "bottom", "id": null}], "rate_conditions": [], "use_active_time": false, "active_start_time": "00:00:00", "active_end_time": "23:59:59", "id": null}'
brainframe-apps alarm-control --cmd delete --stream-id 3 --zone-name ZONE-Door --alarm-name ALRM-person

# Save all alarms to a file, and restore them later
brainframe-apps alarm-control --cmd save --file alarms.json
brainframe-apps alarm-control --cmd load --file alarms.json

Option	Description
`--cmd CMD`	One of `list`, `add`, `delete`, `save`, or `load`. Default: `list`.
`--stream-id`, `--stream-name`, `--stream-url`	The stream to act on.
`--zone-name ZONE_NAME`	The zone that holds the alarm.
`--alarm-name ALARM_NAME`	The name of the alarm to add or delete.
`--options OPTIONS`	The alarm definition as a JSON string. Required for `add`. See the example above.
`--file FILE`	The file to save to or load from. Default: `alarms.json`.

identity-control¶

Manages the identities that capsules can recognize.

brainframe-apps identity-control --cmd list
brainframe-apps identity-control --cmd add --image-path face.png --unique-name EMP-001 --nickname "Alex" --class-name person
brainframe-apps identity-control --cmd delete_all

Option	Description
`--cmd CMD`	One of `list`, `add`, or `delete_all`. Default: `list`.
`--image-path IMAGE_PATH`	The PNG image of the identity, for `add`.
`--unique-name UNIQUE_NAME`	The identity's unique name, for `add`.
`--nickname NICKNAME`	The identity's nickname, for `add`.
`--class-name CLASS_NAME`	The identity's class, for `add`. Default: `person`.

Warning

identity-control --cmd delete_all deletes every identity on the server.

license-control¶

Shows the server's license, or installs a license from a file.

# Show the license state and terms
brainframe-apps license-control

# Install a license
brainframe-apps license-control --license-file license.txt

user-control¶

Signs a user in to a BrainFrame cloud deployment. Use --username and --password for the domain user, or supply OAuth2 tokens with --access-token and --refresh-token. Use --bfm-https-cert to give the certificate of the BrainFrame management server.

Backing Up and Restoring¶

save-settings and load-settings¶

save-settings writes the server's configuration to a JSON file. load-settings applies a saved file to a server, so you can back up a server, copy its configuration to another server, or restore it after a reinstall.

brainframe-apps save-settings --setting-file settings.json
brainframe-apps load-settings --setting-file settings.json --stream-urls config.csv

The saved file includes:

Global capsule options and whether each capsule is active.
The configuration of each stream.
The zones and alarms of each stream.
The capsule options and active state of each stream.

load-settings first restores the global capsule options. It then restores the zones, alarms, and capsule settings of the streams you name with --stream-url or --stream-urls. A stream is matched by its URL, and it must already exist on the server, so add the streams with add-stream first. Camera credentials in the URLs are ignored when matching.

Option	Description
`--setting-file SETTING_FILE`	The settings file. Required for `load-settings`. Default for `save-settings`: `settings.json`.
`--stream-urls STREAM_URLS`	For `load-settings`, the file listing the streams to restore. Default: `stream-urls.csv`.
`--stream-url STREAM_URL`	For `load-settings`, restore this one stream.

Note

Capsule files are not part of the settings file. Load the capsules onto the server before you load the settings.