GStreamer element parameter reference - Amazon Kinesis Video Streams
Provide credentials to kvssinkProvide a region to kvssinkkvssink optional parameters
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

GStreamer element parameter reference

To send video to the Amazon Kinesis Video Streams Producer C++ SDK, you specify kvssink as the sink, or final destination of the pipeline. This reference provides information about kvssink required and optional parameters. For more information, see Example: Kinesis Video Streams Producer SDK GStreamer Plugin - kvssink.

Topics

Provide credentials to kvssink

To allow the kvssink GStreamer element to make requests to Amazon, provide Amazon credentials for it to use when it calls the Amazon Kinesis Video Streams service. The credential provider chain looks for credentials in the following order:

To set up Amazon IoT credentials, see Controlling access to Kinesis Video Streams resources using Amazon IoT.

The iot-credentials parameter value must start with iot-certificate, and be followed by a comma-separated list of the following key=value pairs.

Key Required Description
ca-path Yes

File path to the CA certificate used to establish trust with the backend service through TLS.

Example: /file/path/to/certificate.pem
cert-path Yes

File path to the X.509 certificate.

Example: /file/path/to/certificateID-certificate.pem.crt
endpoint Yes

The Amazon IoT Core credential endpoint provider endpoint for your Amazon account. See the Amazon IoT Developer Guide.

Example: credential-account-specific-prefix.credentials.iot.aws-region.amazonaws.com
key-path Yes

File path to the private key used in the public/private key pair.

Example: /file/path/to/certificateID-private.pem.key
role-aliases Yes

The name of the role alias pointing to the Amazon IAM role to use when connecting to Amazon IoT Core.

Example: KvsCameraIoTRoleAlias
iot-thing-name No

The iot-thing-name is optional. If iot-thing-name is not provided, the stream-name parameter value is used.

Example: kvs_example_camera

Example:

gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" iot-certificate="iot-certificate,endpoint=credential-account-specific-prefix.credentials.iot.aws-region.amazonaws.com,cert-path=certificateID-certificate.pem.crt,key-path=certificateID-private.pem.key,ca-path=certificate.pem,role-aliases=YourRoleAlias,iot-thing-name=YourThingName"

To have kvssink use credentials from the environment, set the following environment variables:

Environment Variable Name Required Description
AWS_ACCESS_KEY_ID Yes The Amazon access key that's used to access Amazon Kinesis Video Streams.
AWS_SECRET_ACCESS_KEY Yes The Amazon secret key associated with the access key.
AWS_SESSION_TOKEN No Specifies the required session token value if you use temporary security credentials directly from Amazon STS operations.

Setting the environment variable changes the value used until the end of your shell session, or until you set the variable to a different value. To make the variables persistent across future sessions, set them in your shell's startup script.

To specify credentials directly as a kvssink parameter, set the following parameters:

kvssink Parameter Name Required Description
access-key Yes The Amazon access key that's used to access Amazon Kinesis Video Streams.
secret-key Yes The Amazon secret key associated with the access key.
session-token No Specifies the required session token value if you use temporary security credentials directly from Amazon STS operations.

Using static credentials:

gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" access-key="AKIDEXAMPLE" secret-key="SKEXAMPLE"

Using temporary credentials:

gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" access-key="AKIDEXAMPLE" secret-key="SKEXAMPLE" session-token="STEXAMPLE"
Important

If you've selected one of the previous methods, you can't use the credential-file kvssink parameter.

kvssink Parameter Name Required Description
credential-file Yes Path to the text file containing credentials in a specific format.

The text file must contain credentials in one of the following formats:

  • CREDENTIALS YourAccessKey YourSecretKey

  • CREDENTIALS YourAccessKey Expiration YourSecretKey SessionToken

Example: Your credentials.txt file is located at /home/ubuntu and contains the following:

CREDENTIALS AKIDEXAMPLE 2023-08-10T22:43:00Z SKEXAMPLE STEXAMPLE

To use it in kvssink, type: 

gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" credential-file="/home/ubuntu/credentials.txt"
Note

The expiration time should be at least 5 + 30 + 3 = 38 seconds in the future. The grace period is defined as the IOT_CREDENTIAL_FETCH_GRACE_PERIOD variable in IotCredentialProvider.h. If the credentials are too close to the expiration when you start kvssink, you receive the error code 0x52000049 - STATUS_INVALID_TOKEN_EXPIRATION.

Important

kvssink doesn't modify the credentials file. If you're using temporary credentials, the credentials file must be updated by an outside source before the expiration time minus the grace period.

Provide a region to kvssink

The following is the region lookup order:

  1. AWS_DEFAULT_REGION environment variable is reviewed first. If it is set, that region is used to configure the client.

  2. aws-region parameter is reviewed next. If it is set, that region is used to configure the client.

  3. If neither of the previous methods were used, kvssink defaults to us-west-2.

kvssink optional parameters

The kvssink element has the following optional parameters. For more information about these parameters, see Kinesis video stream structures.

Parameter Description Unit/ Type Default
stream-name The name of the destination Amazon Kinesis video stream.
Important

If no stream-name is specified, the default stream name will be used: “DEFAULT_STREAM“. If a stream with that default name does not already exist, it will be created.
absolute-fragment-times Whether to use absolute fragment times. Boolean true
access-key

The Amazon access key that's used to access Kinesis Video Streams.

You must either have Amazon credentials set or provide this parameter. To provide this information, type the following:

$ export AWS_ACCESS_KEY_ID=
avg-bandwidth-bps The expected average bandwidth for the stream. Bits per second 4194304
aws-region

The Amazon Web Services Region to use.

Note

You can also provide the region with the AWS_DEFAULT_REGION environment variable. The environment variables take precedence if both the environment variable and kvssink parameters are set.

Important

The region will default to us-west-2 if not otherwise specified.

 String "us-west-2"
buffer-duration The stream buffer duration. Seconds 120
codec-id The codec ID of the stream. String "V_MPEG4/ISO/AVC"
connection-staleness The time after, which the stream staleness callback is called. Seconds 60
content-type The content type of the stream. String "video/h264"
fragment-acks Whether to use fragment ACKs. Boolean true
fragment-duration The fragment duration that you want. Milliseconds 2000
framerate The expected frame rate. Frames per second 25
frame-timecodes Whether to use frame timecodes or generate timestamps using the current time callback. Boolean true
key-frame-fragmentation Whether to produce fragments on a key frame. Boolean true
log-config The log configuration path. String "../kvs_log_configuration"
max-latency The maximum latency for the stream. Seconds 60
recalculate-metrics Whether to recalculate the metrics. Boolean true
replay-duration The duration to roll the current reader backward to replay during an error if restarting is enabled. Seconds 40
restart-on-error Whether to restart when an error occurs. Boolean true
retention-period The length of time the stream is preserved. Hours 2
rotation-period The key rotation period. For more information, see Rotating Customer Master Keys. Seconds 3600
secret-key

The Amazon secret key that's used to access Kinesis Video Streams.

You must either have Amazon credentials set or provide this parameter.

$ export AWS_SECRET_ACCESS_KEY=
session-token Specifies the required session token value if you use temporary security credentials directly from Amazon STS operations.
storage-size The device storage size in MegaBytes (MB). For information about configuring device storage, see StorageInfo. MegaBytes 128
streaming-type The streaming type. Valid values include:

  • 0: real time

  • 1: near real time (not currently supported)

  • 2: offline

 Enum GstKvsSinkStreamingType 0: real time
timecode-scale The MKV timecode scale. Milliseconds 1
track-name The MKV track name. String "kinesis_video"
iot-certificate

Amazon IoT credentials to be used in the kvssink element.

iot-certificate accepts the following keys and values:

Note

The iot-thing-name is optional. If iot-thing-name is not provided, the stream-name parameter value is used.

  • endpoint=iotcredentialsproviderendpoint

  • cert-path=/localdirectorypath /to/certificate

  • key-path=/localdirectorypath /to/private/key

  • ca-path=/localdirectorypath/to/ca-cert

  • role-aliases=role-aliases

  • iot-thing-name=YourIotThingName

 String None