Use Case Library¶

The Use Case Library turns video files and pictures into simulated IP cameras. It stores a collection of sample videos, publishes each of them as a live RTSP stream, and can add the streams to BrainFrame in one step. Use it to demonstrate a use case, test capsules and alarms, or build a test system with many "cameras" without any camera hardware.

For each file, the library provides:

An RTSP stream that looks like an IP camera to BrainFrame and to other RTSP clients, such as VLC.
An HLS stream that plays in a web browser.
A loop: the video plays again from the start when it ends, so the "camera" never goes offline.

Note

The Use Case Library is a separate application. It is not part of the BrainFrame server, and it runs in its own container.

To open the Use Case Library, type the IP address of the BrainFrame OS server in a browser to open the BrainFrame Web Client. Once connected, click the Developer button at the bottom left to bring up the Developer References menu, then click Use Case Library.

Install¶

You need Docker on the machine that will host the library. This can be the BrainFrame server or another machine on the same network.

The library runs as the Docker image aotuai/stream-simulator, and uses these ports:

Port	Use
7090	The web interface.
7554	RTSP streams.
7888	HLS streams.

Using the ide_cli script of the project:

sudo ./ide_cli init   # create the data directory and pull the image
./ide_cli up          # start the library
./ide_cli down        # stop it
./ide_cli logs        # follow the logs

Or with Docker Compose, using the docker-compose.yml of the project:

docker compose up -d

ide_cli up finds the IP address of the machine on its own and uses it in the stream URLs. To use a different address or host name, set VC_SERVER_HOST (see Settings). The library stores its data in /var/local/stream-simulator, so your videos and tags are kept when the container is replaced.

Open the web interface in a browser:

http://<library-host>:7090

The Library Page¶

The page lists the media in the library, grouped into sections (see Organize with Tags). Each row shows:

Item	Description
ID	The number of the stream. It is used in the stream URLs.
File Name	The name of the file, with a thumbnail, its tags, and its resolution and video codec. Click the name to play the original video. An Image badge marks a stream made from a picture.
Size, Duration	The size and length of the file.
HLS Stream	The HLS address. Click the play icon to watch the stream in the browser.
RTSP Stream	The RTSP address. Click it to copy it to the clipboard.
Information icon	The properties of the stream.
Tag icon	Edit the tags of the stream.
Number badge	How many RTSP clients are watching the stream now. The badge is green when at least one client, such as BrainFrame, is reading it, and gray when none is.
Arrow icon	Add this stream to BrainFrame.
Warning icon	The stream could not be verified. Point to it to see the reason.

The stream addresses follow this pattern:

rtsp://<library-host>:7554/mocked_stream_<ID>
http://<library-host>:7888/mocked_stream_<ID>

Add Media¶

Upload a file¶

Click Upload Media.
Click Open and choose a file. Videos can be .mp4 or .avi. Pictures can be .jpg, .jpeg, .png, .webp, .bmp or .gif.
For a video from a fisheye camera, select Fisheye. The video is then flattened into six normal views.
For a picture, set the clip length, from 2 to 300 seconds (default 10). The picture is turned into a video that loops, so the length only sets the size of one loop.
Click Upload. A progress message is shown while the file is processed.

Spaces in the file name are replaced by underscores. A file with the same name as one already in the library is rejected. Pictures can be up to 25 MB, and a GIF uses only its first frame.

Every file is converted once, when it is added, into an MP4 video (H.264, with no B-frames and a key frame every two seconds), which suits RTSP clients and BrainFrame. The original file is kept.

You can also copy files into the resources folder in the data directory. The library checks that folder about once a minute and publishes new files. It supports .mp4, .avi, .webm, .mkv, .mov, and the picture types above. If you delete a file from the folder, its stream is removed.

Add media from a web address¶

Click Add Media URL.
Paste the address. YouTube, Google Drive, and Kaggle links are supported, as well as direct links to a video or a picture.
For a picture, set the clip length. It is ignored for videos.
Click OK.

The address is added to the active configuration (see Share a Library), and appears in the list as an entry that is not downloaded yet. Select the entry and click Fetch Media to download it. A progress message shows in its row, and the entry becomes a normal row when it finishes.

Bulk tagging and Add Videos to BrainFrame are not available for entries that are not downloaded yet.

Remove media¶

Select the rows and click Remove Selected Videos. This deletes the files and their streams.

Add Streams to BrainFrame¶

Select one or more rows, and click Add Videos to BrainFrame. To add a single stream, click the arrow icon in its row.
Check the list of streams. The dialog does not allow addresses that use localhost or 127.0.0.1, because BrainFrame would not be able to reach them. If you see this error, set VC_SERVER_HOST to the address of the library machine, and restart the library.
Enter the BrainFrame OS Server Url. It starts as the address you used to open the library.
Click Apply.

For each stream, the library creates an IP camera stream in BrainFrame, with the file name as the stream name and the RTSP address as its URL. It then starts analyzing the stream. The BrainFrame server must be reachable and be a compatible version, or an error is shown.

The library remembers which BrainFrame servers each stream was added to. Such streams are published all the time. Other streams start only when a client reads them, and stop after a period with no readers. The first connection to an idle stream can therefore take a few seconds.

You can also copy the RTSP address and add the stream by hand in the Web Client, or add many streams at once with REST API Apps.

Tip

Use the library to try the examples in other parts of this documentation without a camera. For example, add a traffic video, load capsules from the AI Marketplace, and then draw zones and create alarms.

Organize with Tags¶

Tags describe what a video shows, so that you can find a video for a use case. A tag has four parts:

Vertical | Category | Use Case | Asset & Events

For example, Transportation & Smart Cities | Traffic Flow & Congestion Management | Vehicle Counting & Classification. The library groups rows into sections by their tag, and a video with several tags appears in each section.

The standard verticals are:

Manufacturing & Industrial
Retail & Hospitality
Transportation & Smart Cities
Enterprise & Smart Buildings
Physical Security & Operations

You can also type your own values.

Action	How
Tag one video	Click the tag icon in its row, choose or type the parts, click Add Tag, then Save.
Tag several videos	Select the rows, click Add Tags, choose the tag, and click Apply.
Remove tags	Click the x on a tag in the row, or select rows and click Remove Tags.
Save tags to a file	Click Export Config. A JSON file is downloaded.
Load tags from a file	Click Import Config.

Select the box in a section header to select every row in the section.

The Media Sources button controls where the library gets its list of remote media from. This list is called a configuration seed. A seed is a shared file that lists media addresses and their tags, so that several people can use the same library without copying video files.

Click Media Sources.
Select Public configuration seed to use the public seed. Clear it to enter the address of your own seed.
Click Pull config from seed. Choose the configuration from the list and click OK.
Fetch the media you need with Fetch Media.

If you add addresses or change tags, the name of the active configuration is shown in red with "unsaved local changes". Click Push config back to seed to share your changes. Files that you uploaded from your computer are never part of a seed.

If you use YouTube, Google Drive, or Kaggle sources, the same dialog sets the credentials the library needs:

Kaggle: your Kaggle user name and API key, from kaggle.com/settings/api.
Google Drive: an OAuth client ID and secret, and then Connect Google Account.

Credentials are saved in the library. Use Clear Credentials or Disconnect to remove them.

When the public seed is active, the list is shown in a lighter, gray theme, and the watermark text is the public one. This makes it clear that you are not looking at your private library.

Settings¶

The library is configured with environment variables. With ide_cli, edit the variables at the top of the script. With Docker Compose, edit the environment section.

Variable	Description	Default
`VC_SERVER_HOST`	The address that is used in the stream URLs. Set it to the IP address or host name that BrainFrame and your browser use to reach the library.	The address of the machine (`ide_cli`)
`VC_SERVER_PORT`	The port of the web interface.	`7090`
`RTSP_PORT`	The port of the RTSP streams.	`7554`
`HLS_PORT`	The port of the HLS streams.	`7888`
`TITLE`	The title at the top of the page.	`Use Case Library`
`WATERMARK_TEXT`	The text that is drawn faintly over the list.	A confidentiality notice
`PUBLIC_WATERMARK_TEXT`	The watermark that is used while the public seed is active.	`CONNECTED TO PUBLIC MEDIA SOURCES.`

If you change a port, also change the matching port mapping of the container.

Troubleshooting¶

The Apply button is disabled in the Add to BrainFrame dialog. A stream address contains localhost or 127.0.0.1. Set VC_SERVER_HOST to the machine's network address and restart the library.

BrainFrame cannot open the stream. Check that the BrainFrame server can reach the library on port 7554, and that no firewall blocks it. Open the RTSP address in VLC to test it. A warning icon in the row means the library could not verify the stream. Point to it to see why.

An upload is rejected. A file with the same name may already be in the library, or the file type is not supported.

A video is slow to appear. The library converts each new video once. Large files, and fisheye videos, take longer.