Streams

BrainFrame works by connecting to and running analysis on video streams. Streams can come from a variety of sources and have analysis be turned on or off at runtime.

Below is an example script that uploads a video file, starts streaming it, and turns on analysis for that stream.

from pathlib import Path

from brainframe.api import BrainFrameAPI
from brainframe.api.bf_codecs import StreamConfiguration, ConnType

api = BrainFrameAPI("http://localhost")

video_bytes = Path("video_file.mp4").read_bytes()
storage_id = api.new_storage(video_bytes, "video/mp4")

stream_config = api.set_stream_configuration(
    StreamConfiguration(
        name="My Video File",
        connection_type=ConnType.FILE,
        connection_options={"storage_id": storage_id},
        runtime_options={},
    ))

api.start_analyzing(stream_config.id)

API Methods

BrainFrameAPI.get_stream_configuration(stream_id, timeout=30)brainframe.api.bf_codecs.config_codecs.StreamConfiguration

Gets the StreamConfiguration with the given ID.

Parameters
  • stream_id – The ID of the stream configuration to get

  • timeout – The timeout to use for this request

Returns

The stream configuration

BrainFrameAPI.get_stream_configurations(premises_id=None, timeout=30) → List[brainframe.api.bf_codecs.config_codecs.StreamConfiguration]

Get all StreamConfigurations that currently exist.

Returns

[StreamConfiguration, StreamConfiguration, …]

BrainFrameAPI.set_stream_configuration(stream_configuration, timeout=30) → Optional[brainframe.api.bf_codecs.config_codecs.StreamConfiguration]

Update an existing stream configuration or create a new one. If creating a new one, the stream_configuration.id will be None.

Parameters
  • stream_configuration – StreamConfiguration

  • timeout – The timeout to use for this request

Returns

StreamConfiguration, initialized with an ID

BrainFrameAPI.start_analyzing(stream_id, timeout=30)

Starts analysis on this stream.

Parameters
  • stream_id – The ID of the stream to start analysis on

  • timeout – The timeout to use for this request

BrainFrameAPI.stop_analyzing(stream_id, timeout=30)

Stops analysis on this stream.

Parameters
  • stream_id – The ID of the stream to stop analysis on

  • timeout – The timeout to use for this request

Returns

True or False if the server was able to start analysis on that stream. It could fail because: unable to start stream, or license restrictions.

BrainFrameAPI.check_analyzing(stream_id, timeout=30) → bool

Check if this stream is being analyzed

Parameters
  • stream_id – The ID of the stream to check

  • timeout – The timeout to use for this request

Returns

True or False if the stream is being analyzed

BrainFrameAPI.delete_stream_configuration(stream_id, timeout=120)

Deletes a stream configuration with the given ID. Also stops analysis if analysis was running and closes the stream.

Parameters
  • stream_id – The ID of the stream to delete

  • timeout – The timeout to use for this request

BrainFrameAPI.get_stream_url(stream_id, timeout=30) → str

Gets the URL that the stream is available at.

Parameters
  • stream_id – The ID of the stream to get a URL for

  • timeout – The timeout to use for this request

Returns

The URL

BrainFrameAPI.get_runtime_options(stream_id: int, timeout=30) → Dict[str, object]

Returns the runtime options for the stream with the given ID. This can also be read from a StreamConfiguration object.

Parameters
  • stream_id – The ID of the stream to get runtime options from

  • timeout – The timeout to use for this request

Returns

Runtime options

BrainFrameAPI.set_runtime_option_vals(stream_id: int, runtime_options: Dict[str, object], timeout=30)

Sets a stream’s runtime options to the given values.

Parameters
  • stream_id – The ID of the stream to set runtime options for

  • runtime_options – The runtime options

  • timeout – The timeout to use for this requestz

Data Structures

class StreamConfiguration(name: str, premises_id: Optional[int], connection_type: brainframe.api.bf_codecs.config_codecs.StreamConfiguration.ConnType, connection_options: dict, runtime_options: dict, metadata: dict = <factory>, id: Optional[int] = None)

Describes a video stream that BrainFrame may connect to and analyze.

class ConnType(value)

An enumeration.

FILE = 'file'

An uploaded video file

IP_CAMERA = 'ip_camera'

A network camera that uses RTSP or HTTP

WEBCAM = 'webcam'

A webcam (usually USB)

classmethod values()
connection_options: dict

Contains configuration describing how this stream can be connected to. The contents of this dict will depend on the connection type.

ConnType.IP_CAMERA:

url: The URL of the IP camera to connect to

pipeline (optional): A custom GStreamer pipeline to connect to the IP camera with

ConnType.FILE:

storage_id: The storage ID of the video file to stream

transcode (optional): If True, the video file will be transcoded before being streamed. By default, this value is True.

pipeline (optional): A custom GStreamer pipeline to connect to the hosted stream of this video file with

ConnType.WEBCAM:

device_id: The Video4Linux device ID of the webcam

connection_type: ConnType

The type of stream this configuration is describing

id: Optional[int] = None

The unique ID of this stream

metadata: dict

Key-value pairs containing some custom user-defined set of data to further describe the stream

name: str

The human-readable name of the video stream

premises_id: Optional[int]

The ID of the premises that this stream is a part of, or None if this stream is not part of a premises

runtime_options: dict

Key-value pairs of configuration information that changes the runtime behavior of the video stream from its defaults