kvs

KVSSkyLine is a SkyLine implementation that streams the output of the AWS Panorama application to AWS Kinesis Video Streams service.

To use this class you MUST have the following dependencies correctly configured on your system:

These dependencies can not be easily specified by a requirements.txt or a Conda environment. See the example Dockerfile on how to install these dependencies on your system.

class backpack.kvs.KVSSkyLine(stream_region, stream_name, credentials_handler, *args, **kwargs)

Bases: SkyLine

Sends OpenCV frames to Kinesis Video Streams.

KVSSkyLine can be used to create programmatically a video stream and send it to AWS Kinesis Video Streams service.

When initializing the KVSSkyLine instance, you should provide the AWS credentials that will be used to stream the video in your AWS account. The KVSCredentialsHandler subclasses implement different ways of passing the credentials to the underlying Kinesis Video Stream Producer. In most of the cases, KVSFileCredentialsHandler with the default arguments should work well, as long as your AWS user or the assumed IAM Role have a policy to put data in KVS.

You can configure the frame width, height and fps auto-detection as described in the SkyLine class documentation.

Parameters:

  • stream_region (str) – The AWS region of the Kinesis Video Stream

  • stream_name (str) – The name of the Kinesis Video Stream

  • credentials_handler (KVSCredentialsHandler) – The credentials handler

  • args (List[Any]) – Positional arguments to be passed to SkyLine initializer.

  • kwargs (Dict[str, Any]) – Keyword arguments to be passed to SkyLine initializer.

class backpack.kvs.KVSCredentialsHandler(aws_access_key_id=None, aws_secret_access_key=None, executor=<concurrent.futures.thread.ThreadPoolExecutor object>, parent_logger=None)

Bases: ABC

Abstract base class for credential providers.

Credential providers provide AWS credentials to Kinesis Video Stream Producer library.

If no static credentials are provided in the init method, the Credentials Handler will figure out the AWS credentials from the boto3 configuration.

Use of static credentials are recommended at most for testing purposes. If you instantiate this class with custom credentials in the init method arguments, or calling the init method from a workstation where you’ve configured an AWS user credentials, you will get static credentials. If the caller code assumed an IAM role, you will use dynamic credentials.

When using dynamic credentials, you are expected to call the check_refresh() method periodically to control the expiration of the dynamic credentials. Ideally you would call this method each time when you want send a new frame to Kinesis Video Streams Producer. If the credentials are not expired, this method should add almost no overhead.

You should not instantiate this class: use one if its subclasses instead.

Parameters:

  • aws_access_key_id (str) – If you want to use custom static credentials, specify your AWS access key ID here. This method is not recommended for production builds.

  • aws_secret_access_key (str) – If you want to use custom static credentials, specify your AWS secret access key here. This method is not recommended for production builds.

  • executor (Executor) – Credential refresh operator will be dispatched to this executor.

  • parent_logger (Logger) – Connect the logger of this class to a parent logger.

REFRESH_BEFORE_EXPIRATION = datetime.timedelta(seconds=120)

Refresh credentials so many seconds before expiration.

check_refresh()

Call this method periodically to refresh credentials.

Return type:

None

plugin_config()

Returns a string that should be included in the kvssink GStreamer plugin config.

Return type:

str

plugin_config_mask(plugin_config)

Masks credentials for printing in logs.

Parameters:

plugin_config (str) –

Return type:

str

class backpack.kvs.KVSInlineCredentialsHandler(*args, **kwargs)

Bases: KVSCredentialsHandler

Provides AWS credentials inline in the kvssink plugin config.

This credentials handler can be used only with static credentials as there is no way to refresh the credentials once they were passed to KVS Producer.

Parameters:
plugin_config()

Returns a string that should be included in the kvssink GStreamer plugin config.

Return type:

str

plugin_config_mask(plugin_config)

Masks credentials for printing in logs.

Parameters:

plugin_config (str) – The original plugin config string.

Return type:

str

class backpack.kvs.KVSEnvironmentCredentialsHandler(*args, **kwargs)

Bases: KVSCredentialsHandler

Saves AWS credentials in environment variables.

Experience shows that the kvssink plugin does not check periodically the environment variables for updated dynamic credentials, so there are chances that your stream will stop once the original dynamic credentials expiry.

For this reason, it is recommended that you use this credentials handler only with static credentials and do not use it in production setting.

Parameters:
class backpack.kvs.KVSFileCredentialsHandler(credentials_path='/tmp/credentials.txt', *args, **kwargs)

Bases: KVSCredentialsHandler

Saves AWS variables in a text file compatible with credential-path parameter of kvssink.

Using this credentials handler establishes the most robust communication between the handler and the Kinesis Video Stream Producer. The credentials are written into a text file with a predefined format. This handler can be used both with static and dynamic credentials: the handler will ensure that the refreshed credentials are updated also in the text file, before the declared file expiration.

Parameters:
FILE_REFRESH_GRACE_PERIOD = datetime.timedelta(seconds=60)

Give some time (60s) to boto3 credentials handler to effectively refresh the credentials, and declare the expiration of the KVS credentials file after the waiting this time, KVS will find the new tokens in the file.

plugin_config()

Returns a string that should be included in the kvssink GStreamer plugin config.

Return type:

str